APIs
Canonical Arxi sidecar API artifacts generated by arxi-contract.
Download: apis/sidecar.openapi.json (22 KB) Download: apis/sidecar.errors.json (3 KB) Download: apis/sidecar.enums.json (696 B) Download: apis/sidecar.compat.json (3.7 KB) Download: apis/sidecar.examples.json (1.5 KB)
OpenAPI Summary
{
"openapi": "3.1.0",
"title": "Arxi Sidecar API",
"version": "1.0",
"paths": 14
}
Operations
| Method | Path | Summary |
|---|---|---|
GET | /health | Liveness probe. |
GET | /ready | Readiness probe. |
GET | /startup | Startup completion probe. |
POST | /v1/bundles/build | Build bundle from selector. |
POST | /v1/bundles/inspect | Inspect bundle metadata. |
POST | /v1/bundles/verify | Verify bundle integrity. |
GET | /v1/config | Get sanitized runtime config. |
POST | /v1/envelopes | Record an envelope. |
POST | /v1/envelopes/with-attachments | Record an envelope with inline attachments. |
POST | /v1/query/envelopes | Query envelopes. |
GET | /v1/segments | List segment metadata. |
POST | /v1/segments | Open a new segment. |
GET | /v1/segments/active | Return active segment metadata. |
POST | /v1/segments/seal | Seal the active segment. |
sidecar.errors.json
{
"api_major_version": 1,
"errors": [
{
"code": "attachment_invalid",
"http_status": 400,
"retryable": false,
"summary": "Attachment payload or metadata is invalid."
},
{
"code": "auth_misconfigured",
"http_status": 500,
"retryable": false,
"summary": "Token auth mode configured without token material."
},
{
"code": "bad_request",
"http_status": 400,
"retryable": false,
"summary": "Request payload is malformed."
},
{
"code": "content_length_invalid",
"http_status": 400,
"retryable": false,
"summary": "Content-Length header is invalid."
},
{
"code": "envelope_invalid",
"http_status": 400,
"retryable": false,
"summary": "Envelope validation failed."
},
{
"code": "filter_invalid",
"http_status": 400,
"retryable": false,
"summary": "Filter or selector is invalid."
},
{
"code": "header_too_large",
"http_status": 431,
"retryable": false,
"summary": "Request headers exceed configured limit."
},
{
"code": "idempotency_conflict",
"http_status": 409,
"retryable": false,
"summary": "Idempotency key reused with different payload hash."
},
{
"code": "idempotency_key_invalid",
"http_status": 400,
"retryable": false,
"summary": "Idempotency-Key header is invalid."
},
{
"code": "idempotency_key_required",
"http_status": 400,
"retryable": false,
"summary": "Idempotency-Key header is required."
},
{
"code": "idempotency_unavailable",
"http_status": 503,
"retryable": true,
"summary": "Idempotency storage is unavailable."
},
{
"code": "internal",
"http_status": 500,
"retryable": true,
"summary": "Unexpected internal failure."
},
{
"code": "no_active_segment",
"http_status": 409,
"retryable": false,
"summary": "No active segment exists for operation."
},
{
"code": "not_acceptable",
"http_status": 406,
"retryable": false,
"summary": "Accept header does not allow JSON."
},
{
"code": "not_found",
"http_status": 404,
"retryable": false,
"summary": "Requested resource was not found."
},
{
"code": "payload_too_large",
"http_status": 413,
"retryable": false,
"summary": "Request body exceeds configured limit."
},
{
"code": "segment_already_active",
"http_status": 409,
"retryable": false,
"summary": "Cannot open a new segment while one is active."
},
{
"code": "segment_empty",
"http_status": 409,
"retryable": false,
"summary": "Cannot seal an empty segment."
},
{
"code": "storage_unavailable",
"http_status": 503,
"retryable": true,
"summary": "Storage backend is unavailable."
},
{
"code": "timeout",
"http_status": 408,
"retryable": true,
"summary": "Request exceeded configured timeout."
},
{
"code": "too_many_requests",
"http_status": 429,
"retryable": true,
"summary": "Request rejected due to admission saturation."
},
{
"code": "transport_bind_failed",
"http_status": 500,
"retryable": false,
"summary": "Transport listener failed to bind."
},
{
"code": "transport_runtime_failed",
"http_status": 500,
"retryable": true,
"summary": "Transport runtime task failed."
},
{
"code": "unauthorized",
"http_status": 401,
"retryable": false,
"summary": "Authorization token is missing or invalid."
},
{
"code": "unsupported_media_type",
"http_status": 415,
"retryable": false,
"summary": "Content-Type must be application/json."
},
{
"code": "verification_failed",
"http_status": 400,
"retryable": false,
"summary": "Bundle verification could not complete successfully."
}
]
}
sidecar.enums.json
{
"api_major_version": 1,
"enum_registries": [
{
"name": "transport_mode",
"wire_type": "string",
"wire_values": [
"unix",
"tcp",
"both"
]
},
{
"name": "security_mode",
"wire_type": "string",
"wire_values": [
"token",
"open"
]
},
{
"name": "auto_seal_mode",
"wire_type": "string",
"wire_values": [
"none",
"after_count",
"after_duration",
"combined"
]
},
{
"name": "log_level",
"wire_type": "string",
"wire_values": [
"error",
"warn",
"info",
"debug",
"trace"
]
},
{
"name": "log_format",
"wire_type": "string",
"wire_values": [
"json",
"pretty"
]
},
{
"name": "segment_status",
"wire_type": "string",
"wire_values": [
"open",
"sealed"
]
},
{
"name": "trust_policy",
"wire_type": "string",
"wire_values": [
"any_trusted_key",
"all_must_sign",
"threshold"
]
}
],
"no_numeric_enums": true
}
sidecar.compat.json
{
"api_major_version": 1,
"baseline": {
"mutating_endpoints_requiring_idempotency": [
{
"method": "post",
"path": "/v1/segments"
},
{
"method": "post",
"path": "/v1/segments/seal"
},
{
"method": "post",
"path": "/v1/envelopes"
},
{
"method": "post",
"path": "/v1/envelopes/with-attachments"
}
],
"required_enum_values": {
"auto_seal_mode": [
"none",
"after_count",
"after_duration",
"combined"
],
"log_format": [
"json",
"pretty"
],
"log_level": [
"error",
"warn",
"info",
"debug",
"trace"
],
"security_mode": [
"token",
"open"
],
"segment_status": [
"open",
"sealed"
],
"transport_mode": [
"unix",
"tcp",
"both"
],
"trust_policy": [
"any_trusted_key",
"all_must_sign",
"threshold"
]
},
"required_error_codes": [
{
"code": "attachment_invalid",
"http_status": 400
},
{
"code": "auth_misconfigured",
"http_status": 500
},
{
"code": "bad_request",
"http_status": 400
},
{
"code": "content_length_invalid",
"http_status": 400
},
{
"code": "envelope_invalid",
"http_status": 400
},
{
"code": "filter_invalid",
"http_status": 400
},
{
"code": "header_too_large",
"http_status": 431
},
{
"code": "idempotency_conflict",
"http_status": 409
},
{
"code": "idempotency_key_invalid",
"http_status": 400
},
{
"code": "idempotency_key_required",
"http_status": 400
},
{
"code": "idempotency_unavailable",
"http_status": 503
},
{
"code": "internal",
"http_status": 500
},
{
"code": "no_active_segment",
"http_status": 409
},
{
"code": "not_acceptable",
"http_status": 406
},
{
"code": "not_found",
"http_status": 404
},
{
"code": "payload_too_large",
"http_status": 413
},
{
"code": "segment_already_active",
"http_status": 409
},
{
"code": "segment_empty",
"http_status": 409
},
{
"code": "storage_unavailable",
"http_status": 503
},
{
"code": "timeout",
"http_status": 408
},
{
"code": "too_many_requests",
"http_status": 429
},
{
"code": "transport_bind_failed",
"http_status": 500
},
{
"code": "transport_runtime_failed",
"http_status": 500
},
{
"code": "unauthorized",
"http_status": 401
},
{
"code": "unsupported_media_type",
"http_status": 415
},
{
"code": "verification_failed",
"http_status": 400
}
],
"required_paths": [
{
"idempotency_required": false,
"method": "get",
"operation_id": "getHealth",
"path": "/health",
"success_statuses": [
200
]
},
{
"idempotency_required": false,
"method": "get",
"operation_id": "getStartup",
"path": "/startup",
"success_statuses": [
200
]
},
{
"idempotency_required": false,
"method": "get",
"operation_id": "getReady",
"path": "/ready",
"success_statuses": [
200,
503
]
},
{
"idempotency_required": true,
"method": "post",
"operation_id": "openSegment",
"path": "/v1/segments",
"success_statuses": [
201
]
},
{
"idempotency_required": true,
"method": "post",
"operation_id": "sealSegment",
"path": "/v1/segments/seal",
"success_statuses": [
200
]
},
{
"idempotency_required": false,
"method": "get",
"operation_id": "listSegments",
"path": "/v1/segments",
"success_statuses": [
200
]
},
{
"idempotency_required": false,
"method": "get",
"operation_id": "getActiveSegment",
"path": "/v1/segments/active",
"success_statuses": [
200
]
},
{
"idempotency_required": true,
"method": "post",
"operation_id": "recordEnvelope",
"path": "/v1/envelopes",
"success_statuses": [
201
]
},
{
"idempotency_required": true,
"method": "post",
"operation_id": "recordEnvelopeWithAttachments",
"path": "/v1/envelopes/with-attachments",
"success_statuses": [
201
]
},
{
"idempotency_required": false,
"method": "post",
"operation_id": "queryEnvelopes",
"path": "/v1/query/envelopes",
"success_statuses": [
200
]
},
{
"idempotency_required": false,
"method": "post",
"operation_id": "buildBundle",
"path": "/v1/bundles/build",
"success_statuses": [
200
]
},
{
"idempotency_required": false,
"method": "post",
"operation_id": "verifyBundle",
"path": "/v1/bundles/verify",
"success_statuses": [
200
]
},
{
"idempotency_required": false,
"method": "post",
"operation_id": "inspectBundle",
"path": "/v1/bundles/inspect",
"success_statuses": [
200
]
},
{
"idempotency_required": false,
"method": "get",
"operation_id": "getRuntimeConfig",
"path": "/v1/config",
"success_statuses": [
200
]
}
]
},
"compatibility_policy": {
"breaking_changes_require_major_bump": true,
"deprecation_overlap_days_minimum": 180,
"v1": "additive_only"
}
}
sidecar.examples.json
{
"api_major_version": 1,
"examples": {
"buildBundle.request": {
"selector": {
"BySegment": "019478a2-2d50-7d6a-8e2a-84c31f2f2001"
}
},
"error.response": {
"client_correlation_id": "client-test-001",
"code": "envelope_invalid",
"detail": "event_type invalid",
"retryable": false,
"server_correlation_id": "018f7de8-2d50-7d6a-8e2a-84c31f2f1001",
"status": 400,
"title": "Bad Request",
"type": "urn:arxi:sidecar:error:envelope_invalid"
},
"getHealth.response.200": {
"recorder_id": "sidecar:production-01",
"status": "ok",
"version": "0.1.0"
},
"getReady.response.200": {
"active_segment": "019478a2-2d50-7d6a-8e2a-84c31f2f2001",
"chain_head": "ab12cd34",
"envelope_count": 42,
"ready": true,
"reason": null
},
"getStartup.response.200": {
"recorder_id": "sidecar:production-01",
"started": true,
"startup_verification_depth": 100,
"version": "0.1.0"
},
"openSegment.response.201": {
"created_at": "2026-02-07T14:30:00.000000000Z",
"genesis_hash": "ab12cd34",
"segment_id": "019478a2-2d50-7d6a-8e2a-84c31f2f2001"
},
"recordEnvelope.request": {
"actor_id": "agent:test-agent",
"claimed_time": "2026-02-07T14:30:00.000000000Z",
"environment_id": "env:ci-pipeline",
"event_type": "agent.step.completed",
"parent_id": null,
"payload": {
"result": "pass",
"step": "verify"
},
"session_id": null,
"trace_id": "trace-abc-123"
},
"recordEnvelope.response.201": {
"chain_hash": "cd34ef56",
"content_hash": "ab12cd34",
"envelope_id": "019478b3-2d50-7d6a-8e2a-84c31f2f2001",
"recorded_at": "2026-02-07T14:30:00.123456789Z",
"sequence": 0
},
"verifyBundle.request": {
"bundle": {
"id": "018f7de8-2d50-7d6a-8e2a-84c31f2f3001"
},
"trust_root": null
}
}
}