Task APIs

Headers

The request headers that change how a task call is handled, and the headers every answer carries.

These are request options, not task inputs. A task's input is the JSON body, checked against its schema; a header changes how the call is handled — whether it is safe to retry, how long to wait, when to give up. The two stay separate: a header is sent with the HTTP request, a task input is a field of the body.

Idempotency-Key

Makes a retried submit safe: the same key with the same body answers the first job again instead of starting a second one.


Header	`Idempotency-Key`
Default	none — every submit starts a new job
Format	an opaque string; use a UUID v4
Where it applies	`POST /v1/tasks/{name}` only; other operations ignore it

import uuid
key = str(uuid.uuid4())  # once per operation, kept with it
s.post(f"{API}/tasks/image.generate", json=body, headers={"Idempotency-Key": key})

The same key with a different body answers 409 idempotency_key_reused; nothing runs.

Idempotency →

Prefer: wait

Holds the submit's answer until the job ends, up to N seconds.


Header	`Prefer: wait=N`
Default	absent: the submit answers `202` at once
Unit	seconds, a whole number
Max	60; a larger `N` is cut to it
Where it applies	`POST /v1/tasks/{name}`

Prefer: wait=30

A job that ends within N seconds answers 200 with its result; otherwise you get the usual 202 and the job keeps running. A malformed Prefer is treated as no wait. Set your HTTP client's timeout longer than N.

Synchronous →

X-Refabric-Start-Timeout

Despite the name, this limits time-to-start, not the run: a job that has not started within this many seconds of the submit ends without running.


Header	`X-Refabric-Start-Timeout`
Default	absent: the job waits in the queue as long as it takes
Unit	seconds; decimals allowed
Min	0.1
Max	86400
Values	a value outside the range, or not a number, answers `422 invalid_request` naming the header
Where it applies	`POST /v1/tasks/{name}`

X-Refabric-Start-Timeout: 30

A job that misses its start deadline fails with start_timeout, releases its credit hold, and the answer about it carries X-Refabric-Start-Timeout-Type: user.

Start deadline →

Refabric-Version

Pins the dated contract version you wrote against.


Header	`Refabric-Version`
Default	absent: the current version
Format	a date, `YYYY-MM-DD`
Values	the published versions; any other value answers `400 invalid_request`
Where it applies	every operation; every answer echoes the version it followed

Refabric-Version: <a published version date>

Versioning →

X-Request-ID

Your own id for a request, logged next to ours.


Header	`X-Request-ID`
Default	absent
Format	a short id of letters, digits and `. _ : -`; the exact rule is in Conventions
Where it applies	every operation

X-Request-ID: order-4711-render

Every answer carries OUR id in X-Request-ID (req_…) — quote it to support. Yours comes back as X-Client-Request-ID. An id that does not fit the format is dropped, never refused.

Support →

webhook_url

A query parameter, not a header: the address we POST the job's terminal event to.


Parameter	`?webhook_url=https://…`
Default	absent: no per-job callback
Format	an `https://` URL that resolves to a public address
Where it applies	`POST /v1/tasks/{name}`

curl -s -X POST "https://api.refabric.com/v1/tasks/image.generate?webhook_url=https://example.com/hooks/refabric" \
  -H "Authorization: Key $REFABRIC_API_KEY" -H "Content-Type: application/json" -d @body.json

A webhook_url we will not deliver to is refused at submit, before anything is held. It receives the terminal events only; registered endpoints can receive more.

Webhooks →

Response headers

Header	On	Meaning
`X-Request-ID`	every answer	our id for the request (`req_…`)
`X-Client-Request-ID`	answers to a request that sent a valid `X-Request-ID`	your id, echoed
`Refabric-Version`	every answer	the contract version the answer follows
`X-Refabric-Credits`	a submit of a task that costs credits	the credits held for the job
`X-Refabric-Credit-Type`	the same answers	the credit type of that hold
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`	answers to a request made with a key	the state of the key's rate window (Limits)
`Retry-After`	`429`	seconds until you may call again
`X-Refabric-Error-Type`	every error answer	the error's `type`, the same as `error.type`
`X-Refabric-Start-Timeout-Type`	an answer about a job that missed its start deadline	`user`: the deadline was yours

Conventions

The rules every operation follows.

Asynchronous jobs

What the submit answers and how a job runs.