Rebuild items from spans
const url = 'https://example.com/api/v1/org/example/ws/example/projects/example/items/rebuild';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"run_ids":["example"],"session_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}'};
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/projects/example/items/rebuild \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "run_ids": [ "example" ], "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'On-demand reconcile: re-materialize a run/session’s item spans from ClickHouse, refreshing derived data and healing failed POSTs while preserving disposition. Operator/system action (items:admin).
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Organization slug
Organization slug
Workspace slug
Workspace slug
Project slug or UUID
Project slug or UUID
Request Bodyrequired
Section titled “Request Bodyrequired”On-demand reconcile: re-materialize a run/session’s item spans from ClickHouse into the items table.
Spans are the source of record; this refreshes derived data (and heals any
item whose direct POST failed) while preserving disposition. Provide a
session_id (most common) and/or explicit run_ids (capped — rebuild
is a scoped recovery sweep, not a bulk backfill).
object
Examplegenerated
{ "run_ids": [ "example" ], "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}Responses
Section titled “ Responses ”Successful Response
Sweep accounting. All fields beyond processed are additive (defaulted)
so N-1 clients keep working.
skipped: envelopes not attempted (malformed, or payload offloaded to
object storage). failed: envelopes attempted but rolled back (e.g. ref
clash, unknown session). links_failed: items that landed but whose
inline links could not be applied (e.g. a target ref matching nothing in
the project). truncated: the span fetch hit its bound and the sweep is
incomplete — re-scope and rerun.
object
Example
{ "failed": 0, "links_failed": 0, "skipped": 0, "truncated": false}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"}