Platform API › Tasks

Run a task

202 with the new job's job_id and its status, result and cancel URLs — or, while waiting, the job's result itself.

POSThttps://api.refabric.com/v1/tasks/{name}

import os
import requests

url = "https://api.refabric.com/v1/tasks/{name}"

payload = {}
headers = {
    "Authorization": f"Key {os.environ['REFABRIC_API_KEY']}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

{
  "job_id": "9b2f4c1d0e8a",
  "files": [],
  "has_more": false,
  "next_cursor": null,
  "summary": {}
}

Modes

1. Asynchronous (the default) — answers 202 at once; follow the job at its status URL, or name a webhook_url to be called when it ends.
2. Wait (Prefer: wait=N) — holds the answer up to N seconds and answers the result when the job ends in time; otherwise 202, as when asynchronous.

Authentication. A key with tasks:run: a job spends your credits.

Key features

Prefer: wait waits 60 seconds at most.
X-Refabric-Start-Timeout takes 0.1 seconds to 24 hours: a job that has not started by then ends without starting.
A webhook is tried up to 31 times.
A body field the task's input schema (GET /v1/tasks/{name}) does not list is refused (422 field_not_accepted, naming it), never ignored.

Common use cases

Start a job from your server and poll it or wait for its webhook.
Run a short job and take its result in the same call with Prefer: wait.

Conflicts. An Idempotency-Key sent again with another body answers 409 idempotency_key_reused; sent again while the first request runs, 409 request_in_progress.

See also

POST /v1/tasks/{name}/estimate
GET /v1/jobs/{job_id}
GET /v1/tasks/{name}

Authorization

Authorization: Key $REFABRIC_API_KEYScope: tasks:run

Parameters

Path parameters

stringrequired

Query parameters

stringoptionalDefault:
An https endpoint of yours to POST the result to. Signed with ED25519 — verify it with /.well-known/jwks.json. Tried up to 31 times; a 3xx or 4xx is final.

Header parameters

stringoptional
The contract version you wrote against (a date). Absent: the current version.
format: date
stringoptional
Your own id for this request; we answer it back under X-Client-Request-ID.
max length 128
stringoptional
Makes a retry safe: the same key with the same request answers the first answer again; with a different request it is refused.
stringoptional
wait=N: hold the answer up to N seconds for the job to end (60 at most).
numberoptional
Seconds the job may wait to start, from 0.1 to 86400; past it, it ends without running.

Body

application/json

Response

200 — Done: the answer is in the body.

stringrequired
The job.
Example: 9b2f4c1d0e8a
array<object>required
The files, in the order the job delivered them.
- stringrequired
  Where the file is. A public, permanent address you can open or download.
  Example: https://files.refabric.com/art/3f2a.png
- stringrequired
  The file's standard media type.
  Example: image/png
- stringrequired
  Its address; pass it to a task as it is.
  Example: art:3f2a
- stringoptionalnullable
  The task that made it.
  Example: image.expand
- stringoptionalnullable
  The job that made it.
  Example: 9b2f4c1d0e8a
- stringoptionalnullable
  When it was made, ISO-8601 in UTC.
  Example: 2026-10-05T09:30:12Z
- objectoptionalnullable
  What the file means, in the record vocabulary.
booleanrequired
More files are on the next page.
Example: false
stringoptionalnullable
Present when has_more: send it as cursor to the result read for the rest.
objectoptionalnullable
Present when the task has words to count.
- integeroptionalnullable
  Outputs asked for.
  Example: 3
- integeroptionalnullable
  Outputs made.
  Example: 2
- array<object>optionalnullable
  Notes on what was not made.

202 — Accepted: the work goes on after this answer; the body says where to follow it.

stringrequired
The job you started.
Example: 9b2f4c1d0e8a
stringrequired
Where the job is now.
Values
- queued — Accepted and waiting to start.
- running — Being made.
- terminal — Ended. outcome says how.
Example: queued
stringrequired
Read the job here (GET), as often as you like.
Example: http://v3-api.refabric.com/v1/jobs/9b2f4c1d0e8a
stringrequired
Read its result here (GET) once it has succeeded.
Example: http://v3-api.refabric.com/v1/jobs/9b2f4c1d0e8a/result
stringrequired
Ask for it to stop here (PUT).
Example: http://v3-api.refabric.com/v1/jobs/9b2f4c1d0e8a/cancel

400 — The request cannot be read as it was sent (a header, the URL or the body's form).
401 — No valid API key was sent.
402 — Your balance does not cover this request.
403 — Your key or your plan does not allow this.
404 — Nothing has this address.
409 — The request conflicts with the current state of what it names.
410 — This was removed.
413 — The body is larger than this operation takes.
415 — The body's media type is not one this operation takes.
422 — A field is missing or has a value this operation cannot use.
429 — Too many requests: wait for the number of seconds in the Retry-After header.
500 — Something went wrong on our side; retry, and quote the request id if it keeps happening.
503 — The service cannot take this now; retry after a moment.

import os
import requests

url = "https://api.refabric.com/v1/tasks/{name}"

payload = {}
headers = {
    "Authorization": f"Key {os.environ['REFABRIC_API_KEY']}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

{
  "job_id": "9b2f4c1d0e8a",
  "files": [],
  "has_more": false,
  "next_cursor": null,
  "summary": {}
}