API overview

emit has one HTTP API, with JSON bodies. The SDKs and the CLI are built on it, so anything they do, you can do with curl.

Base URL

Each cluster has its own address: its endpoint, shown on the cluster's Overview page in the dashboard. Every path in this reference follows it:

POST https://<your cluster's endpoint>/v1/spaces/orders/jobs

The examples read it from $EMIT_URL, and an API token from $EMIT_TOKEN.

Authentication

Send an API token in the Authorization header:

curl -s "$EMIT_URL/v1/spaces/orders/jobs?limit=10" -H "Authorization: Bearer $EMIT_TOKEN"

See Authentication for scopes, and for making and revoking tokens.

Requests and responses

• Request bodies are JSON: send Content-Type: application/json.
• Field names are camelCase: maxAttempts, createdAtMs.
• Times are milliseconds. A name ending in Ms is a duration (timeoutMs), and one ending in AtMs is a Unix time (createdAtMs).
• Numbers that can be larger than 32 bits, such as times, come back as strings: "createdAtMs": "1790726132737". You can send them as numbers or strings.
• Statuses and other fixed values are upper case: "status": "COMPLETED", "scopes": ["CREATE", "READ"]. Send them in upper case too: ?status=FAILED.
• Your own data (a payload, a result, an event, a signal's data) goes in and comes back as the JSON you sent. Its keys may come back in a different order.
• A field emit doesn't know is refused with 400.

Batches

The calls that change jobs take many at once. Creating 500 jobs in one request is far faster than 500 requests. Send an array, or an object with the list under its name, or a single object for a batch of one:

[{ "name": "resize-image", "payload": { "imageId": "img_881" } }, { "name": "resize-image", "payload": { "imageId": "img_882" } }]

The answer has one entry per item, in the order you sent them. Each one is a result or a rejection of its own, so check every entry, not only the HTTP status:

{ "outcomes": [{ "status": "CANCELLED" }, { "rejection": { "reason": "ALREADY_FINISHED", "message": "" } }] }

Errors

A request that's refused as a whole gets an HTTP error status and a JSON body:

{ "code": "PermissionDenied", "message": "the token's scopes do not allow this", "retryAfterMs": null }

Retrying is safe for 429 and 5xx. For creates, give each job a key so that a retry can't make it twice. See When emit is busy.

Pagination

Lists are newest first. Ask for up to 1,000 at a time with limit. The answer's nextPage is where the next page starts: pass it back as page. An empty nextPage means there's nothing more. From emit 0.6 a page can be shorter than limit, even empty, and still have a nextPage: keep asking until nextPage comes back empty, and never stop at a short page.

curl -s "$EMIT_URL/v1/spaces/orders/jobs?name=send-receipt&limit=100" -H "Authorization: Bearer $EMIT_TOKEN"
# {"jobs":[...],"nextPage":"01M3QSRN3703HA2Z5PZY8WPRQB"}

curl -s "$EMIT_URL/v1/spaces/orders/jobs?name=send-receipt&limit=100&page=01M3QSRN3703HA2Z5PZY8WPRQB" \
  -H "Authorization: Bearer $EMIT_TOKEN"

Streams

Following a job returns a stream: server-sent events by default, or a WebSocket if you ask for an upgrade. Each message is one JSON event. See Follow a job.

Reference