APIs
القطع الأثرية لواجهة برمجة التطبيقات الجانبية المسجلة التي تم إنشاؤها بواسطة recorder-contract.
تحميل: apis/sidecar.openapi.json (34 كيلوبايت) تحميل: apis/sidecar.errors.json (3 كيلوبايت) تحميل: apis/sidecar.enums.json (696 بايت) تحميل: apis/sidecar.compat.json (4.1 كيلوبايت) تحميل: apis/sidecar.examples.json (2.5 كيلوبايت)
ملخص OpenAPI
{
"openapi": "3.1.0",
"title": "Recorder Sidecar API",
"version": "1.0",
"paths": 13
}
العمليات
| الطريقة | المسار | الملخص |
|---|---|---|
GET | /health | اختبار الحيادية. |
GET | /ready | اختبار الجاهزية. |
GET | /startup | اختبار اكتمال بدء التشغيل. |
POST | /v1/bundles/build | بناء حزمة من المحدد. |
POST | /v1/bundles/inspect | فحص بيانات التعريف للحزمة. |
POST | /v1/bundles/verify | التحقق من سلامة الحزمة. |
GET | /v1/config | الحصول على إعدادات التشغيل المعقمة. |
POST | /v1/envelopes | تسجيل ظرف. |
POST | /v1/envelopes/with-attachments | تسجيل ظرف مع مرفقات داخلية. |
POST | /v1/ingest/otel | استيراد سجلات تصدير OpenTelemetry بتنسيق JSON. |
POST | /v1/query/envelopes | استعلام عن الظروف ضمن تدفق واحد. |
GET | /v1/segments | قائمة بيانات التعريف للقطاعات. |
GET | /v1/segments/active | قائمة بيانات التعريف للقطاعات النشطة. |
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/envelopes"
},
{
"method": "post",
"path": "/v1/envelopes/with-attachments"
},
{
"method": "post",
"path": "/v1/ingest/otel"
}
],
"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": [
{
"accepted_request_media_types": [],
"idempotency_required": false,
"method": "get",
"operation_id": "getHealth",
"path": "/health",
"success_statuses": [
200
]
},
{
"accepted_request_media_types": [],
"idempotency_required": false,
"method": "get",
"operation_id": "getStartup",
"path": "/startup",
"success_statuses": [
200
]
},
{
"accepted_request_media_types": [],
"idempotency_required": false,
"method": "get",
"operation_id": "getReady",
"path": "/ready",
"success_statuses": [
200,
503
]
},
{
"accepted_request_media_types": [],
"idempotency_required": false,
"method": "get",
"operation_id": "listSegments",
"path": "/v1/segments",
"success_statuses": [
200
]
},
{
"accepted_request_media_types": [],
"idempotency_required": false,
"method": "get",
"operation_id": "listActiveSegments",
"path": "/v1/segments/active",
"success_statuses": [
200
]
},
{
"accepted_request_media_types": [
"application/json"
],
"idempotency_required": true,
"method": "post",
"operation_id": "recordEnvelope",
"path": "/v1/envelopes",
"success_statuses": [
201
]
},
{
"accepted_request_media_types": [
"application/json"
],
"idempotency_required": true,
"method": "post",
"operation_id": "recordEnvelopeWithAttachments",
"path": "/v1/envelopes/with-attachments",
"success_statuses": [
201
]
},
{
"accepted_request_media_types": [
"application/json"
],
"idempotency_required": false,
"method": "post",
"operation_id": "queryEnvelopes",
"path": "/v1/query/envelopes",
"success_statuses": [
200
]
},
{
"accepted_request_media_types": [
"application/json"
],
"idempotency_required": false,
"method": "post",
"operation_id": "buildBundle",
"path": "/v1/bundles/build",
"success_statuses": [
200
]
},
{
"accepted_request_media_types": [
"application/json"
],
"idempotency_required": false,
"method": "post",
"operation_id": "verifyBundle",
"path": "/v1/bundles/verify",
"success_statuses": [
200
]
},
{
"accepted_request_media_types": [
"application/json"
],
"idempotency_required": false,
"method": "post",
"operation_id": "inspectBundle",
"path": "/v1/bundles/inspect",
"success_statuses": [
200
]
},
{
"accepted_request_media_types": [
"application/json"
],
"idempotency_required": true,
"method": "post",
"operation_id": "ingestOtel",
"path": "/v1/ingest/otel",
"success_statuses": [
201
]
},
{
"accepted_request_media_types": [],
"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": "pre_release_break"
}
}
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:recorder: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"
},
"ingestOtel.request": {
"resourceLogs": [],
"resourceSpans": [
{
"scopeSpans": [
{
"spans": [
{
"endTimeUnixNano": "1735689601000000000",
"name": "http.request",
"spanId": "0123456789abcdef",
"startTimeUnixNano": "1735689600000000000",
"traceId": "0123456789abcdef0123456789abcdef"
}
]
}
]
}
]
},
"ingestOtel.response.201": {
"anomaly_count": 0,
"first_global_commit_index": 129,
"first_stream_sequence": 17,
"idempotency_outcome": "accepted",
"last_chain_hash": "8ab4f12f22cb47f5db0bc5f5ce0f7eddfb0f4b80f5dc6a4de9807f95ceef6cfb",
"last_global_commit_index": 130,
"last_stream_sequence": 18,
"log_count": 1,
"mapping_version": "otel_recorder_v1",
"receipt_id": "f5f779a20d8ef4bbf57fd66b5e611abca9472785fca990df8c10e2f43f0306d1",
"record_count": 2,
"request_hash": "d9b42a81e6c4868f8b60a3d5cfe83d15d8aa9450b26ff23b3ab3ce17f6f18a6a",
"span_count": 1,
"stream_key": {
"recorder_id": "sidecar:production-01",
"tenant_id": 1
}
},
"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"
},
"recorder_id": "sidecar:production-01",
"session_id": null,
"tenant_id": 1,
"trace_id": "trace-abc-123"
},
"recordEnvelope.response.201": {
"chain_hash": "cd34ef56",
"commit_timestamp": "2026-02-07T14:30:00.123456789Z",
"content_hash": "ab12cd34",
"envelope_id": "019478b3-2d50-7d6a-8e2a-84c31f2f2001",
"global_commit_index": 128,
"idempotency_outcome": "accepted",
"receipt_id": "6be9fd69b2ebbf2dc562f5ec514f413ef5fb3f7db012a8dbcdde8a59be79f0de",
"request_hash": "89ab3f8f94dfaf774de4b5af7f377b1d339838fbcf4fd9c51694a5f35db634f4",
"stream_key": {
"recorder_id": "sidecar:production-01",
"tenant_id": 1
},
"stream_sequence": 16
},
"verifyBundle.request": {
"bundle": {
"id": "018f7de8-2d50-7d6a-8e2a-84c31f2f3001"
},
"trust_root": null
}
}
}