For AI agents: this page is also available as Markdown at https://docs.refabric.com/task-apis/calling-tasks/overview.md, and the index of every page is https://docs.refabric.com/llms.txt.
Task APIs › Calling tasks
Calling tasks
The ways to submit a task and learn that its job has ended, and when to use each.
Every task call is POST /v1/tasks/{name} and starts a job. What differs is how you hear back: you
poll the job, you hold the submit open until it ends, or we call you. The recommended way is to
submit and poll, or to submit and receive a webhook.
| Method | How it works | When |
|---|---|---|
| Submit and poll (recommended) | the submit answers 202 at once; read status_url until lifecycle is terminal, then result_url | the default for every task |
Wait (Prefer: wait=N) | the submit holds its answer up to N seconds; a job that ends in time answers 200 with its result | short jobs, scripts, tests |
Webhook per job (?webhook_url=) (recommended) | we POST the job's terminal event to your URL | long jobs, when your server can receive a request |
| Registered webhook endpoints | an endpoint registered in Panel › Developers › Webhooks receives the events of every job started with your keys | many jobs; progress events |
The methods combine: a Prefer: wait submit that runs out of time answers 202, and you poll from
there; a job with a webhook can still be polled.