Composition API Reference

On this page

The composition engine (ADR-035): resolves the composed dashboard and case-detail surfaces by merging the jurisdiction baseline, the jurisdiction-live override (written from the Studio admin surface), and the worker’s own personalization layer.

Endpoints

compositions

Resolve the composed surface named by {surface} for the acting worker.

GET /v1/compositions/{surface}

Authz-gated (Action::Read on the composition resource); the post-merge role filter then governs which panels the worker’s role actually sees. The resolution role, jurisdiction, and user_sub come from the request principal — honoring the ADR-028 X-Craig-Actor on-behalf-of actor when present. The user_sub makes the worker’s own personalization (the Plan X Step 9 user layer) apply on read, so a personalized layout "survives reload"; a service principal / non-UUID subject resolves the role baseline (no user layer).

Table 1. Parameters
Name In Required Description

surface

path

Yes

Surface to resolve: dashboard or case_detail
Responses

  • 200: The merged, role-filtered surface with its content version

  • 401: Missing or invalid bearer token

  • 403: The principal may not read compositions

  • 404: Unknown surface

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

GET /v1/compositions/{surface}/override — the current jurisdiction-live

override delta + ETag, or 404 when the jurisdiction has not customized this surface yet.

GET /v1/compositions/{surface}/override

Table 2. Parameters
Name In Required Description

surface

path

Yes

dashboard or case_detail
Responses

  • 200: The current jurisdiction-live override + its ETag

  • 403: Not permitted to manage composition overrides

  • 404: Unknown surface, or no override set yet

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

PUT /v1/compositions/{surface}/override — write the jurisdiction-live

override (validate → persist + stage-invalidation in one txn → evict cache).

PUT /v1/compositions/{surface}/override

Table 3. Parameters
Name In Required Description

surface

path

Yes

dashboard or case_detail
Responses

  • 200: Written; returns the new ETag

  • 400: Missing precondition, or the override would break the surface

  • 403: Not permitted to manage composition overrides

  • 404: Unknown surface, or If-Match replace with no existing row

  • 409: Optimistic-concurrency conflict (ETag mismatch / already exists)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

GET /v1/compositions/{surface}/user-delta — the acting worker’s current

personalization envelope + ETag, or 404 when they have not personalized this surface yet.

GET /v1/compositions/{surface}/user-delta

Table 4. Parameters
Name In Required Description

surface

path

Yes

dashboard (the only personalizable surface)
Responses

  • 200: The worker’s current user_delta_v1 envelope + its ETag

  • 400: The acting worker is a service principal or has no UUID subject

  • 403: Not permitted to read compositions

  • 404: Unknown surface, or no personalization set yet

  • 422: The surface does not support user-delta personalization

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

PUT /v1/compositions/{surface}/user-delta — validate + persist the acting

worker’s personalization (validate per X4 → persist + stage-invalidation in one txn → evict this worker’s cache entry).

PUT /v1/compositions/{surface}/user-delta

Table 5. Parameters
Name In Required Description

surface

path

Yes

dashboard (the only personalizable surface)
Responses

  • 200: Written; returns the new ETag

  • 400: Missing precondition, malformed request body, or the acting worker has no UUID subject

  • 403: Not permitted to read compositions

  • 404: Unknown surface, or If-Match replace with no existing row

  • 409: Optimistic-concurrency conflict (ETag mismatch / already exists)

  • 422: The surface is unsupported, or the delta is invalid (unknown slug / forbidden panel / over-budget row)

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Edit this page · latest