Control API conventions

This concept guide summarizes the frozen docs/04-api/CONVENTIONS.md (CC-004). Control API operations and Bridge operations publish their own exact schemas and security declarations.

Authentication and workspace scope

Send Authorization: Bearer <JWT> issued by the configured OIDC provider. BellD validates issuer, audience, expiry, and signature. Authorization uses the resolved identity context. A workspace path must match that context. Foreign-workspace or absent resources return 404; a known identity with insufficient role within its workspace receives 403. Responses include x-correlation-id.

Errors

Errors use RFC 9457 Problem Details (application/problem+json). Branch on stable code, not human detail. Keep the correlation_id for diagnosis. reason can refine a capability failure; validation errors may contain errors with path and message. Standard error codes are generated from CONVENTIONS.

{
  "type": "https://belld.dev/errors/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "input_type must be one of: git_repository",
  "instance": "/v1/workspaces/ws_EXAMPLE/products",
  "code": "validation_failed",
  "correlation_id": "evt_EXAMPLE"
}

Lists and responses

Lists return items and next_cursor (null at the end). The default limit is 50, maximum 200, unless the operation specifies otherwise. Treat cursors as opaque. Default order is descending by ID; order=asc selects ascending. Success responses are resource or list objects without a data wrapper. Large objects use URI, SHA-256 and size references.

Writes and idempotency

POST creation accepts Idempotency-Key (at most 256 characters). Replays return the original result and Idempotent-Replayed: true. Creation normally returns 201, state transitions 200, and asynchronous acceptance 202. Inspect the operation schema for exact status codes and response bodies.

Naming and versioning

Paths use kebab-case plural resources under /v1; JSON fields use snake_case. IDs are opaque. Times use ISO 8601 UTC with Z. Additive fields, endpoints and enum values are compatible: clients must tolerate unknown fields and values. Breaking changes use a new prefix such as /v2 with a transition period.