Documentation
Guides for building against Sheptra: the managed BPMN engine, its HTTP API, and the workers you run in your own services. Each page is written from a file in the engine’s repository and names that file, so what you read here is what the engine enforces — where the two disagree, the page is the bug.
Available now#
- Workers LiveThe worker environment block, minting a token, and the job loop — everything a service needs to pick up jobs from a Sheptra environment.
- Environments LiveCreate, place, suspend, resume and delete your organization’s environments from Drive — where an environment lands, what two environments share and never share, the plan card, and what deleting one does to its data and to the workers bound to it.
- Forms LiveDesign a form for a user task in the Modeler, bind it by key, deploy it to the environment, and complete the task through it in Drive or over the task API.
- API reference LiveThe two HTTP hosts every environment exposes, where each serves its OpenAPI document and interactive reference, and what /v1 promises.
Planned#
The rest of the documentation plan, tracked as GRE-566. None of these pages exists yet; the numbers are the ticket’s own items, kept so the plan and this page cannot drift apart.
| Page | Covers | State |
|---|---|---|
| Getting started | Sign in, create an environment and an API client, paste the environment block, first deploy, first worker. | Not written |
| Start and drive processes | Starting instances by key, variables, messages and signals, user tasks, incidents. | Not written |
| Error catalogue | Every 4xx and 5xx a worker can receive, with retry guidance for each. | Not written |
| Discovery and machine bindings | Config mode versus discovery mode in depth, and binding machine credentials to environments. The environment lifecycle has its own page. | Not written |
| BPMN support, FEEL, DMN, limits | The element support matrix, the FEEL reference, decision tables, and the request and payload limits. | Not written |
| Drive and Modeler walkthroughs | The operator and modeling surfaces, screen by screen. | Not written |
Until then#
The machine-readable contract is the OpenAPI document every environment serves at /openapi/v1.json, with an interactive reference over it at /docs on the same host — the API reference page explains the two hosts and links to each. Point a generator or an API client at the document to explore every endpoint.