Append facts from the executing host
const url = 'https://example.com/api/v1/org/example/ws/example/workflows/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/facts';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"execution_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","facts":[{"attempt":1,"idempotency_key":"example","kind":"example","occurred_at":"2026-04-15T12:00:00Z","payload":{},"seq":1,"unit_key":"example"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/org/example/ws/example/workflows/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/facts \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "execution_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "facts": [ { "attempt": 1, "idempotency_key": "example", "kind": "example", "occurred_at": "2026-04-15T12:00:00Z", "payload": {}, "seq": 1, "unit_key": "example" } ] }'Idempotent on (run, seq); folds only the gap-free prefix.
A batch that arrives ahead of a gap is stored and reported as buffered
rather than rejected — the host ships best-effort and later fills the hole.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Organization slug
Organization slug
Workspace slug
Workspace slug
Request Body required
Section titled “Request Body required ”object
One fact as the executing host produced it.
seq is assigned by the host — the only party that knows execution order.
The platform accepts appends idempotently on (run, seq) and folds only a
gap-free prefix, so the projection is always behind, never wrong.
Responses
Section titled “ Responses ”Successful Response
What the platform did with the batch.
buffered is the honest part: facts ahead of a gap are stored but not yet
folded, so a client can tell the difference between “applied” and “waiting
for the fact you have not sent yet”.
object
Example generated
{ "accepted": 1, "buffered": 1, "duplicates": 1, "last_fact_seq": 1, "run_status": "example"}Invalid request
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Authentication failed
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Access forbidden
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Not found
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Already exists
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Validation error
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Upgrade required
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Rate limited
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Internal server error
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Bad gateway
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Gateway timeout
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}