For AI agents: this page is also available as Markdown at https://docs.refabric.com/api-reference/platform/webhooks/events.md, and the index of every page is https://docs.refabric.com/llms.txt.
Platform API › Webhooks
Event reference
job.started
A job left the queue and started (opt-in; once per job).
- stringrequired
The event's id — the same on every retry of one delivery. Deduplicate on it: a delivery may arrive more than once.
Example:
5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90 - stringrequired
When it happened, ISO-8601 in UTC.
Example:
2026-10-05T09:30:12Z - stringrequired
Which event this is.
Values
job.started
Example:
job.started - stringrequired
The API version the body is written in (
Refabric-Version).Example:
2026-09-29 - stringrequired
The job the event is about.
Example:
9b2f4c1d0e8a - stringrequired
The task the job runs.
Example:
image.expand - stringrequired
Where the job is.
Values
queued— Accepted and waiting to start.running— Being made.terminal— Ended.outcomesays how.
Example:
running - stringrequirednullable
How the job ended —
nulluntil itslifecycleisterminal.Values
succeeded— It finished; its files are ready.failed— It ended without its result;errorsays why.cancelled— You cancelled it.
- objectrequired
How far the job got.
Example:
{"done":0,"phase":"","total":1}- integerrequired
Files delivered so far.
Example:
2 - integerrequirednullable
Files the job plans to deliver;
nulluntil it is known.Example:
4 - stringrequired
What the job is doing now; may be empty.
Example:
{
"id": "5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90",
"occurred_at": "2026-10-05T09:30:12Z",
"event": "job.started",
"api_version": "2026-09-29",
"job_id": "9b2f4c1d0e8a",
"task": "image.expand",
"lifecycle": "running",
"outcome": null,
"progress": {
"done": 0,
"phase": "",
"total": 1
}
}job.progress
A job delivered one more output; the payload carries progress {done, total, phase} (opt-in; at most once per delivery, unordered — read progress.done).
- stringrequired
The event's id — the same on every retry of one delivery. Deduplicate on it: a delivery may arrive more than once.
Example:
5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90 - stringrequired
When it happened, ISO-8601 in UTC.
Example:
2026-10-05T09:30:12Z - stringrequired
Which event this is.
Values
job.progress
Example:
job.progress - stringrequired
The API version the body is written in (
Refabric-Version).Example:
2026-09-29 - stringrequired
The job the event is about.
Example:
9b2f4c1d0e8a - stringrequired
The task the job runs.
Example:
image.expand - stringrequired
Where the job is.
Values
queued— Accepted and waiting to start.running— Being made.terminal— Ended.outcomesays how.
Example:
running - stringrequirednullable
How the job ended —
nulluntil itslifecycleisterminal.Values
succeeded— It finished; its files are ready.failed— It ended without its result;errorsays why.cancelled— You cancelled it.
- objectrequired
How far the job got.
Example:
{"done":0,"phase":"","total":1}- integerrequired
Files delivered so far.
Example:
2 - integerrequirednullable
Files the job plans to deliver;
nulluntil it is known.Example:
4 - stringrequired
What the job is doing now; may be empty.
Example:
{
"id": "5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90",
"occurred_at": "2026-10-05T09:30:12Z",
"event": "job.progress",
"api_version": "2026-09-29",
"job_id": "9b2f4c1d0e8a",
"task": "image.expand",
"lifecycle": "running",
"outcome": null,
"progress": {
"done": 0,
"phase": "",
"total": 1
}
}job.succeeded
A job finished and its files are ready.
- stringrequired
The event's id — the same on every retry of one delivery. Deduplicate on it: a delivery may arrive more than once.
Example:
5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90 - stringrequired
When it happened, ISO-8601 in UTC.
Example:
2026-10-05T09:30:12Z - stringrequired
Which event this is.
Values
job.succeeded
Example:
job.succeeded - stringrequired
The API version the body is written in (
Refabric-Version).Example:
2026-09-29 - stringrequired
The job the event is about.
Example:
9b2f4c1d0e8a - stringrequired
The task the job runs.
Example:
image.expand - stringrequired
Where the job is.
Values
queued— Accepted and waiting to start.running— Being made.terminal— Ended.outcomesays how.
Example:
running - stringrequired
How the job ended.
Values
succeeded
Example:
succeeded - objectrequired
How far the job got.
Example:
{"done":0,"phase":"","total":1}- integerrequired
Files delivered so far.
Example:
2 - integerrequirednullable
Files the job plans to deliver;
nulluntil it is known.Example:
4 - stringrequired
What the job is doing now; may be empty.
Example:
- objectrequired
The first page of the job's result, as
GET /v1/jobs/{job_id}/resultanswers it.Example:
{"files":[],"has_more":false,"job_id":"9b2f4c1d0e8a"}- 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.
- stringoptionalnullable
The record's name.
Example:
SS27 - stringoptionalnullable
What the record is, in words.
Example:
A calm palette. - stringoptionalnullable
Whether it can be used yet.
Values
processing— Still being made or analysed. Read it again later.ready— Finished. It can be passed to a task.failed— It could not be made. Its content is missing.
Example:
ready - array<object>optionalnullable
Its colours.
Example:
[{"hex":"#1f2a44"}]- stringrequired
The colour as
#rrggbb.Example:
#1f2a44 - stringoptionalnullable
Its name, when known.
Example:
Navy - stringoptionalnullable
The nearest Pantone code, when known.
Example:
19-4024 TCX
- array<object>optionalnullable
Its parts (a pose preset: its poses and views).
Example:
[{"type":"fabric"}]ItemEntry
- stringrequired
What the part is.
Values
fabric— A fabric: its swatch or a photo of it. When the image is a fabric swatch or a photo of a fabric.print— A print or pattern. When the image is a print or pattern.look— A garment or outfit, as a photo or a design. When the image is a garment or an outfit.detail— A close crop of one detail of a look or a product (a collar, a pocket). When the image is a close crop of one detail.design— One cell of a range plan: a design made for one garment line.other— Any other image the record holds. When the image is none of the other kinds.product— A photo of the product itself, as supplied (view: which side). When the photo is the product itself;viewsays which side.label— A photo of the product's label (care, size or brand label). When the photo is of the product's label.ghost— The product on an invisible (ghost) mannequin (view: which side). When you want the product shown on an invisible mannequin.flat— The product laid flat, as a flat-lay photo (view: which side). When you want the product laid flat.close_up— A close-up of the product's fabric and finish (one per product in a shoot). Notdetail, which is a crop of one trim or component of a look. When you want a close-up of the product's fabric and finish.
Example:
fabric - stringoptionalnullable
Which side it shows.
Example:
front - stringoptionalnullable
Its name.
Example:
Wool twill - stringoptionalnullable
Your own id for it, when you sent one.
Example:
SKU-1 - stringoptionalnullable
What it is, in words.
Example:
A navy wool twill. - stringoptionalnullable
Its image — pass it to a task as it is.
Example:
https://files.refabric.com/art/3f2a.png - stringoptionalnullable
Whether it can be used yet.
Values
processing— Still being made or analysed. Read it again later.ready— Finished. It can be passed to a task.failed— It could not be made. Its content is missing.
Example:
ready
PresetItem
- stringrequired
How the entry names what it wants: a saved pose, an image, words, or a product view.
Example:
view - stringrequired
The pose's address (
pose:…); empty for a view.Example:
pose:812 - stringrequirednullable
The pose's camera angle.
Example:
front - stringrequirednullable
The product view it shows.
Example:
back
- array<string>optionalnullable
Words that sum it up.
Example:
["tailoring"]
- booleanrequired
More files are on the next page.
Example:
false - stringoptionalnullable
Present when
has_more: send it ascursorto 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.
- stringrequired
The warning's catalogue code.
Example:
output_not_produced - stringrequired
What happened, in words.
Example:
This pose was not made. - stringoptionalnullable
The request field it is about.
Example:
poses.items[1]
{
"id": "5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90",
"occurred_at": "2026-10-05T09:30:12Z",
"event": "job.succeeded",
"api_version": "2026-09-29",
"job_id": "9b2f4c1d0e8a",
"task": "image.expand",
"lifecycle": "running",
"outcome": "succeeded",
"progress": {
"done": 0,
"phase": "",
"total": 1
},
"result": {
"files": [],
"has_more": false,
"job_id": "9b2f4c1d0e8a"
}
}job.failed
A job failed. The payload carries the error.
- stringrequired
The event's id — the same on every retry of one delivery. Deduplicate on it: a delivery may arrive more than once.
Example:
5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90 - stringrequired
When it happened, ISO-8601 in UTC.
Example:
2026-10-05T09:30:12Z - stringrequired
Which event this is.
Values
job.failed
Example:
job.failed - stringrequired
The API version the body is written in (
Refabric-Version).Example:
2026-09-29 - stringrequired
The job the event is about.
Example:
9b2f4c1d0e8a - stringrequired
The task the job runs.
Example:
image.expand - stringrequired
Where the job is.
Values
queued— Accepted and waiting to start.running— Being made.terminal— Ended.outcomesays how.
Example:
running - stringrequired
How the job ended.
Values
failed
Example:
failed - objectrequired
How far the job got.
Example:
{"done":0,"phase":"","total":1}- integerrequired
Files delivered so far.
Example:
2 - integerrequirednullable
Files the job plans to deliver;
nulluntil it is known.Example:
4 - stringrequired
What the job is doing now; may be empty.
Example:
- objectrequired
Why it failed, in the shape of every error.
- stringrequired
The catalogued code.
- stringrequired
What kind of failure.
Values
invalid_request— The request cannot be used as sent; fix it and send again.authentication— No valid API key was sent.permission— Your key or your plan does not allow this.not_found— Nothing of yours has this address, or it was removed.conflict— The request conflicts with the current state of what it names.insufficient_credits— Your balance does not cover this request.rate_limited— Too many requests; wait and retry.content_refused— The inputs were refused.processing_failed— The job ran and failed.internal— Something went wrong on our side.warning— Not an error: a note on a job that succeeded.
- stringrequired
What happened, in words.
- booleanrequired
Whether the same request may succeed later.
- stringoptional
The request field it is about, when one is.
- stringoptional
The code's page; absent while the docs have no address.
- stringoptional
The request's id, to quote to support.
- objectoptional
Facts about this error, by the keys its code declares (
GET /v1/errors); absent when there are none. Ignore a key you do not know.- integeroptional
The credits this request needs.
- integeroptional
The credits your balance holds now.
- integeroptional
Seconds to wait before the next call.
- anyoptional
What you sent for
field, shortened; absent when it is not echoed (a file, an object or a secret never is). - stringoptional
The job that failed, when a run waited for it (
Prefer: wait) and it ended in this error. Read it again atGET /v1/jobs/{job_id}; absent on every other error. - integeroptionaldeprecated
Deprecated: read
ctx.required(same value). - integeroptionaldeprecated
Deprecated: read
ctx.balance(same value).
{
"id": "5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90",
"occurred_at": "2026-10-05T09:30:12Z",
"event": "job.failed",
"api_version": "2026-09-29",
"job_id": "9b2f4c1d0e8a",
"task": "image.expand",
"lifecycle": "running",
"outcome": "failed",
"progress": {
"done": 0,
"phase": "",
"total": 1
},
"error": {
"code": "string",
"type": "invalid_request",
"message": "string",
"field": "string",
"retryable": true,
"docs": "string",
"request_id": "string",
"ctx": {
"required": 0,
"balance": 0,
"retry_after": 0
},
"input": null,
"job_id": "string",
"required": 0,
"balance": 0
}
}job.cancelled
A job was cancelled.
- stringrequired
The event's id — the same on every retry of one delivery. Deduplicate on it: a delivery may arrive more than once.
Example:
5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90 - stringrequired
When it happened, ISO-8601 in UTC.
Example:
2026-10-05T09:30:12Z - stringrequired
Which event this is.
Values
job.cancelled
Example:
job.cancelled - stringrequired
The API version the body is written in (
Refabric-Version).Example:
2026-09-29 - stringrequired
The job the event is about.
Example:
9b2f4c1d0e8a - stringrequired
The task the job runs.
Example:
image.expand - stringrequired
Where the job is.
Values
queued— Accepted and waiting to start.running— Being made.terminal— Ended.outcomesays how.
Example:
running - stringrequired
How the job ended.
Values
cancelled
Example:
cancelled - objectrequired
How far the job got.
Example:
{"done":0,"phase":"","total":1}- integerrequired
Files delivered so far.
Example:
2 - integerrequirednullable
Files the job plans to deliver;
nulluntil it is known.Example:
4 - stringrequired
What the job is doing now; may be empty.
Example:
- objectrequired
The catalogued
cancellederror, in the shape of every error.- stringrequired
The catalogued code.
- stringrequired
What kind of failure.
Values
invalid_request— The request cannot be used as sent; fix it and send again.authentication— No valid API key was sent.permission— Your key or your plan does not allow this.not_found— Nothing of yours has this address, or it was removed.conflict— The request conflicts with the current state of what it names.insufficient_credits— Your balance does not cover this request.rate_limited— Too many requests; wait and retry.content_refused— The inputs were refused.processing_failed— The job ran and failed.internal— Something went wrong on our side.warning— Not an error: a note on a job that succeeded.
- stringrequired
What happened, in words.
- booleanrequired
Whether the same request may succeed later.
- stringoptional
The request field it is about, when one is.
- stringoptional
The code's page; absent while the docs have no address.
- stringoptional
The request's id, to quote to support.
- objectoptional
Facts about this error, by the keys its code declares (
GET /v1/errors); absent when there are none. Ignore a key you do not know.- integeroptional
The credits this request needs.
- integeroptional
The credits your balance holds now.
- integeroptional
Seconds to wait before the next call.
- anyoptional
What you sent for
field, shortened; absent when it is not echoed (a file, an object or a secret never is). - stringoptional
The job that failed, when a run waited for it (
Prefer: wait) and it ended in this error. Read it again atGET /v1/jobs/{job_id}; absent on every other error. - integeroptionaldeprecated
Deprecated: read
ctx.required(same value). - integeroptionaldeprecated
Deprecated: read
ctx.balance(same value).
{
"id": "5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90",
"occurred_at": "2026-10-05T09:30:12Z",
"event": "job.cancelled",
"api_version": "2026-09-29",
"job_id": "9b2f4c1d0e8a",
"task": "image.expand",
"lifecycle": "running",
"outcome": "cancelled",
"progress": {
"done": 0,
"phase": "",
"total": 1
},
"error": {
"code": "string",
"type": "invalid_request",
"message": "string",
"field": "string",
"retryable": true,
"docs": "string",
"request_id": "string",
"ctx": {
"required": 0,
"balance": 0,
"retry_after": 0
},
"input": null,
"job_id": "string",
"required": 0,
"balance": 0
}
}