API reference

Source: sheptra.core/docs/http-api.md § OpenAPI · sheptra.core/docs/management-api.md § Modeler API · sheptra.core/docs/api-versioning.md

Every Sheptra environment exposes two HTTP hosts, and each serves its own contract: a machine-readable OpenAPI document at /openapi/v1.json and an interactive reference over it at /docs, where you can browse every endpoint and try requests from the browser. Both are readable without a token — the contract holds no secrets — and are rate-limited per client like every other anonymous route.

The two hosts#

• EngineDefinitions, instances, jobs, tasks, incidents, messages, signals — the runtime API your services and workers call.Interactive referenceOpenAPI documentA dedicated environment has its own host; Drive’s API-client reveal prints it as SHEPTRA_API_URL. Local development: http://localhost:5210.
• ManagementEnvironments, discovery, API clients, members, the Modeler library — the organization-wide API Drive and the Modeler use.Interactive referenceOpenAPI documentOne host for the whole organization, whichever environments it has. Local development: http://localhost:5220.

The engine is what a worker talks to — see Workers for the environment block, the token and the job loop. The management host is what Drive and the Modeler use; a service calls it for discovery (which engine host serves an environment) and for the organization’s own records.

What the documents carry#

Every operation has a one-line summary and a description written from the engine’s own source, so a generated client carries them as doc comments. The document’s info.version is the release the host runs, and its description states the organization-scoping and tenancy rules and the compatibility promise below. Point a generator at the document to build a typed client; the .NET worker SDK, Sheptra.Client, is written against the same contract.

GET /v1/system

{
  "role": "engine",
  "version": "0.1.0",
  "contracts": { "api": 1, "worker": 1, "bridge": { "serves": 1 } }
}

What /v1 promises#

Within a contract number the API only grows. New endpoints, new optional parameters, new response fields and new values on fields documented as open sets ship without notice, so a client must tolerate additive change — ignore fields and values it does not know. Removing or renaming anything, narrowing a type, changing a status code or the problem shape, or making an optional input required is breaking, and breaking changes ship under a new contract (/v2), never in place.

A deprecated element keeps working for at least six months after it is announced. Its responses carry Deprecation and Sunset headers and a Link to its successor, the operation is marked deprecated in the document, and the change is listed in the release notes. The full policy, including the worker and deploy-bridge contracts, is docs/api-versioning.md in the engine repository.