Esacode

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

  1. Open the blueprint and choose Publish. An endpoint runs a published version, never the draft, so edits in progress cannot reach your app.
  2. Open the project's API tab, choose the blueprint, and give the endpoint a name.
  3. Choose the version it runs: always the latest published (publishing a new version changes what your app gets) or one version, fixed.
  4. 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.
  5. 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"
}
CallWhat 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>/runsStarts 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>/cancelStops a run that is still going.
  • Waiting. wait holds 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 its url, with ?wait= if you like, until done is true.
  • Status is queued, running, succeeded, failed or canceled. A run that failed or was stopped has an error in 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) or text. 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"}.

StatusCodeMeaning
400bad_jsonThe body is not a JSON object.
401no_key, bad_keyNo key, or a key that does not open this endpoint.
403endpoint_disabled, endpoint_owner, planTurned off; its maker may no longer run the project; the plan has no endpoints.
404not_foundNo such run of this endpoint.
409cannot_run, no_versionIt cannot run now, with the reason: no worker free, a problem in the blueprint, nothing published.
413too_largeThe body is over 256 KB.
422bad_inputAn input the endpoint does not have, or a value of the wrong kind or out of range.
429too_manyPast 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.