Docs / Run and ship
API endpoints
Publish a blueprint as an endpoint so your own app, service or CI can run it: send inputs, read the results as JSON.
What an endpoint is
An endpoint gives a blueprint an address and a key. Your app sends the inputs to the address, EsaSim runs the blueprint on the project's workers, and the app reads what the run made. Use it to put what you built and tested behind your own product: a moderation step for pictures users upload, a nightly regression sweep started by CI, a report made on request.
The app sees only that endpoint. It cannot read the blueprint, the project, your data or anything else of the workspace, and it can set only the inputs you chose.
Make one
- Open the blueprint and choose Publish. An endpoint runs a published version, never the draft, so edits in progress cannot reach your app.
- Open the project's API tab, choose the blueprint, and give the endpoint a name.
- Choose the version it runs: always the latest published (publishing a new version changes what your app gets) or one version, fixed.
- Tick the settings a call may set, and name each. They are settings of the blueprint's worker blocks: text, numbers, yes/no and choices. Everything else stays as published. Keys, datasets and folders can never be set by a call.
- Set how many calls an hour it takes and how long a run may last, then Make the endpoint.
The key is shown once. It starts with esf_. Keep it on your app's server, never in a web page or a phone app. New key replaces it at once; Turn off refuses calls until you turn it on again.
Endpoints are part of Pro and Enterprise. Making one needs the editor role in the project. Its runs are made in your name, with your role, on the workers you may use for the project, and show in Runs like any other, marked as started through the endpoint. If you leave the project, the endpoint stops.
Call it
curl -X POST https://<your EsaSim address>/api/v1/endpoints/<id>/runs \
-H "Authorization: Bearer esf_…" \
-H "Content-Type: application/json" \
-d '{"inputs": {"sources": "https://example.com/a.jpg", "threshold": 0.8}, "wait": 20}'
The answer (201) is the run:
{
"id": 4127,
"status": "succeeded",
"done": true,
"version": 6,
"outputs": [
{"block": "review", "block_title": "Review pictures", "path": "review/decisions.csv", "size": 412,
"url": "https://…", "rows": [{"item": "a.jpg", "label": "ok", "confidence": 0.97, "reason": "…"}]},
{"block": "review", "path": "review/result.json", "size": 61, "url": "https://…", "json": {"kept": 1, "removed": 0}}
],
"links_expire_at": "2026-11-16T19:22:53+00:00",
"url": "https://<your EsaSim address>/api/v1/endpoints/<id>/runs/4127"
}
| Call | What it does |
|---|---|
GET /api/v1/endpoints/<id> | What the endpoint is: its blueprint, version, inputs (with type, default and range) and limits. |
POST /api/v1/endpoints/<id>/runs | Starts a run. Body: {"inputs": {name: value}, "wait": seconds}, both optional. Up to 256 KB. |
GET /api/v1/endpoints/<id>/runs/<run> | The run now; ?wait=20 waits for its end. |
POST /api/v1/endpoints/<id>/runs/<run>/cancel | Stops a run that is still going. |
- Waiting.
waitholds the answer until the run ends, for up to 25 seconds. A run still going then comes back with"done": false: read it again at itsurl, with?wait=if you like, untildoneis true. - Status is
queued,running,succeeded,failedorcanceled. A run that failed or was stopped has anerrorin words. - Outputs. Every file the run made, with the block that made it and a link that works for an hour without a key. Small JSON, CSV and text files that reached EsaSim (up to 256 KB each, 1 MB together) are in the answer itself:
json,rows(a CSV as objects keyed by its header) ortext. Larger files stay on the worker and are fetched when their link is opened. - Large inputs. Send links, not content: for pictures or files, give their addresses to a block that downloads them (Download files) or reads a bucket.
Errors
Errors are JSON: {"error": "code", "message": "words"}.
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_json | The body is not a JSON object. |
| 401 | no_key, bad_key | No key, or a key that does not open this endpoint. |
| 403 | endpoint_disabled, endpoint_owner, plan | Turned off; its maker may no longer run the project; the plan has no endpoints. |
| 404 | not_found | No such run of this endpoint. |
| 409 | cannot_run, no_version | It cannot run now, with the reason: no worker free, a problem in the blueprint, nothing published. |
| 413 | too_large | The body is over 256 KB. |
| 422 | bad_input | An input the endpoint does not have, or a value of the wrong kind or out of range. |
| 429 | too_many | Past the endpoint's calls an hour. |
What to know
- Workers. Runs go to the workers you may use for the project. If none is online, the call answers 409, or the run waits in the queue: keep a worker on for a service that must answer at any time.
- Speed. A call starts a run of the whole blueprint, so answers take seconds to minutes, not milliseconds. It suits batches and jobs, not a request per keystroke.
- Record. Every call is a run with its version, inputs, workers and files, and is in the audit log with the endpoint's name.
- A worked example. From a blueprint to your app builds a picture review, tests it and calls it from Python and JavaScript.
- From a browser. Call it from your server. The key gives the right to start runs on your workers, so it must not be in code people can read.