API reference

Spaces

Read and change a space's settings, list spaces, and count a space's jobs.

A space is created by its first job, or by setting it up here first.

Get a space

GET /v1/spaces/{space} · scope read

Shell

curl -s "$EMIT_URL/v1/spaces/emails" -H "Authorization: Bearer $EMIT_TOKEN"

JSON

{
  "name": "emails",
  "fifo": false,
  "defaultMaxAttempts": 4,
  "defaultBackoffMs": 1000,
  "defaultBackoff": { "kind": "EXPONENTIAL", "maxMs": 3600000, "multiplierPercent": 200, "jitter": "NONE" },
  "defaultTimeoutMs": "300000",
  "unclaimedMs": "604800000",
  "maxEvents": 1000,
  "maxUnfinished": "0",
  "claimsPerMinute": 0,
  "publicSubscriptions": "SIGNED",
  "webhookSecret": ""
}

A space that has no jobs and was never set up reads as the defaults. The answer also has keysHonouredMs, retainHotMs and retainMs, which are always "0" here: those windows are set for the whole cluster, not per space.

Change a space

PUT /v1/spaces/{space} · scope admin

Creates the space, or replaces its settings. The body is the whole set: a setting you leave out goes back to its default, except webhookSecret, defaultBackoff and unclaimedMs, which stay as they are when left out. To change one setting, get the space, change it, and send it all back.

defaultMaxAttemptsintegerdefault: 4

Tries for each job, counting the first. From 1 to 100.

defaultBackoffMsintegerdefault: 1000

The wait after a job's first failure, in milliseconds.

defaultBackoffobjectdefault: exponential, ×2, up to an hour

How the waits after that grow: kind (EXPONENTIAL, LINEAR or CONSTANT), maxMs (the longest wait, at most an hour), multiplierPercent (100 to 1000; 200 doubles), jitter (NONE, FULL or EQUAL). Send {} to go back to the default.

defaultTimeoutMsintegerdefault: 300000

The lease a worker gets on each attempt, unless it asks for another.

unclaimedMsintegerdefault: 604800000 (7 days)

A job no worker claims within this time fails for good. 0 turns it off; otherwise from a second to a year.

maxEventsintegerdefault: 1000

Events kept per job, up to 3,000.

maxUnfinishedintegerdefault: 0

Refuse new jobs with 429 while the space has this many unfinished. Applied on each shard of the cluster separately. 0 is no limit.

claimsPerMinuteintegerdefault: 0

Jobs handed to workers per minute. Applied on each shard separately. 0 is no limit.

fifobooleandefault: false

Hand jobs out strictly in the order they were created. Set it before the space's first job: it can't change after.

publicSubscriptionsstringdefault: SIGNED

Who may follow a job without an API token: SIGNED (with a follow token), UNSIGNED (anyone with the id) or DISABLED.

webhookSecretstring

Signs callbacks and wake-ups, up to 256 characters. Write-only: it always reads back empty. Leave it out, or empty, to keep the current one.

wakeobject

Where to POST when jobs are waiting: url, optional headers, names (only these job names; empty for all), perWake (jobs one wake-up stands for; 1 unless set) and rewakeMs (wake again after this while jobs are unclaimed; 30,000 unless set). See Wake-ups.

curlTypeScriptGo

curl -s -X PUT "$EMIT_URL/v1/spaces/reports" \
  -H "Authorization: Bearer $EMIT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultMaxAttempts": 6,
    "defaultTimeoutMs": 600000,
    "webhookSecret": "whsec_4f9c1e7b2a8d"
  }'

await admin.spaces.configure("reports", { defaultMaxAttempts: 6, defaultTimeoutMs: 600_000, webhookSecret: "whsec_4f9c1e7b2a8d" });

_, err := admin.Spaces.Configure(ctx, emit.Space{Name: "reports", DefaultMaxAttempts: 6, DefaultTimeoutMs: 600_000, WebhookSecret: "whsec_4f9c1e7b2a8d"})

The answer is the space as it is now, in the same shape as Get a space.

List spaces

GET /v1/spaces · scope admin

Shell

curl -s "$EMIT_URL/v1/spaces" -H "Authorization: Bearer $EMIT_ADMIN_TOKEN"

Answers {"spaces": [...]}, each as Get a space shows it.

Count a space's jobs

GET /v1/spaces/{space}/counts · scope read

Shell

curl -s "$EMIT_URL/v1/spaces/orders/counts" -H "Authorization: Bearer $EMIT_TOKEN"

JSON

{
  "byStatus": { "pending": "2", "running": "0", "completed": "1", "failed": "0", "cancelled": "1" },
  "byName": {
    "send-receipt": {
      "byStatus": { "pending": "0", "running": "0", "completed": "1", "failed": "0", "cancelled": "0" },
      "claimedAtMs": "1790726132760"
    }
  }
}

Pending and running counts are what's there now. Completed, failed and cancelled are totals since the space began. claimedAtMs is when a worker last took a job of that name, "0" for never: a quick way to spot a job name that nobody serves.