{ "openapi": "3.1.0", "info": { "title": "Context4 Public API", "version": "1.0.0", "description": "Versioned public HTTP surface (/v1): tool discovery, executions (202 + idempotency), connections (hosted auth links), and tool sessions (MCP credentials). Errors are RFC7807-style problems with stable codes; list endpoints use opaque cursor pagination; every response carries X-Request-Id." }, "servers": [ { "url": "https://ctx4.me", "description": "Current Context4 deployment" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ctx4__", "description": "Context4 API key (Authorization: Bearer ctx4_...). Issue keys from the dashboard; the secret is shown exactly once." } }, "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "code": { "type": "string", "enum": [ "validation_failed", "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "invalid_oauth_token", "oauth_token_expired", "oauth_grant_revoked", "workspace_selection_required", "capability_missing", "forbidden", "not_found", "conflict", "idempotency_conflict", "execution_not_cancellable", "session_expired", "session_revoked", "session_call_budget_exhausted", "rate_limited", "quota_exceeded", "connector_version_unavailable", "provider_unavailable", "service_unavailable", "internal" ] }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "detail": { "type": "string", "maxLength": 256 } }, "required": [ "type", "title", "status", "code", "request_id" ], "additionalProperties": false, "description": "RFC7807-style problem document. `code` is the stable machine-readable registry entry." }, "ToolListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ToolSummary" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "ToolSummary": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}\\.[a-z0-9][a-z0-9_.]{1,78}$", "example": "bitrix24.contact.create" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "connector_version": { "type": "string", "minLength": 1, "maxLength": 40 }, "operation_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.]{1,78}$", "example": "contact.create" }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "id", "connector_id", "connector_version", "operation_id", "name", "description" ], "additionalProperties": false }, "ToolDetail": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}\\.[a-z0-9][a-z0-9_.]{1,78}$", "example": "bitrix24.contact.create" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "connector_version": { "type": "string", "minLength": 1, "maxLength": 40 }, "operation_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.]{1,78}$", "example": "contact.create" }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "input_schema": {}, "output_schema": {} }, "required": [ "id", "connector_id", "connector_version", "operation_id", "name", "description" ], "additionalProperties": false, "description": "Tool with its pinned JSON-schema documents (published catalog version)" }, "PublicIdentity": { "type": "object", "properties": { "organization_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "organization_id", "workspace_id" ], "additionalProperties": false }, "Execution": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "status": { "type": "string", "enum": [ "requested", "queued", "running", "retrying", "succeeded", "failed", "rejected", "cancelled" ] }, "source": { "type": "string", "enum": [ "dashboard", "api", "mcp", "compat" ] }, "user_id": { "$ref": "#/components/schemas/ExecutionEndUserRef" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "connector_version": { "type": "string", "minLength": 1, "maxLength": 40 }, "operation_id": { "type": "string", "minLength": 1, "maxLength": 160 }, "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "tool_session_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "denial_code": { "type": [ "string", "null" ], "enum": [ "policy_denied", "quota_exhausted", "connector_version_unavailable", "connection_unavailable", "session_denied", null ] }, "failure_code": { "type": [ "string", "null" ], "enum": [ "provider_timeout", "provider_rate_limited", "provider_unavailable", "connection_revoked", "invalid_input", "provider_rejected", "attempt_lost", "engine_error", "retries_exhausted", null ] }, "attempt_count": { "type": "integer", "minimum": 0 }, "max_attempts": { "type": "integer", "exclusiveMinimum": 0 }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "queued_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "id", "status", "source", "user_id", "connector_id", "connector_version", "operation_id", "connection_id", "tool_session_id", "project_id", "denial_code", "failure_code", "attempt_count", "max_attempts", "next_retry_at", "version", "created_at", "updated_at", "queued_at", "finished_at" ], "additionalProperties": false }, "ExecutionEndUserRef": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 _.:@-]{0,255}$" }, "CreateExecutionRequest": { "type": "object", "properties": { "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "operation_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.]{1,78}$", "example": "contact.create" }, "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "tool_session_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "tool_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}\\.[a-z0-9][a-z0-9_.]{1,78}$", "example": "bitrix24.contact.create" }, "project_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "input": { "description": "Bounded JSON payload (<= 64 KiB serialized)" } }, "additionalProperties": false }, "ExecutionListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Execution" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "ExecutionWithResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "status": { "type": "string", "enum": [ "requested", "queued", "running", "retrying", "succeeded", "failed", "rejected", "cancelled" ] }, "source": { "type": "string", "enum": [ "dashboard", "api", "mcp", "compat" ] }, "user_id": { "$ref": "#/components/schemas/ExecutionEndUserRef" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "connector_version": { "type": "string", "minLength": 1, "maxLength": 40 }, "operation_id": { "type": "string", "minLength": 1, "maxLength": 160 }, "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "tool_session_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "denial_code": { "type": [ "string", "null" ], "enum": [ "policy_denied", "quota_exhausted", "connector_version_unavailable", "connection_unavailable", "session_denied", null ] }, "failure_code": { "type": [ "string", "null" ], "enum": [ "provider_timeout", "provider_rate_limited", "provider_unavailable", "connection_revoked", "invalid_input", "provider_rejected", "attempt_lost", "engine_error", "retries_exhausted", null ] }, "attempt_count": { "type": "integer", "minimum": 0 }, "max_attempts": { "type": "integer", "exclusiveMinimum": 0 }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "queued_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "result": { "$ref": "#/components/schemas/ExecutionResult" } }, "required": [ "id", "status", "source", "user_id", "connector_id", "connector_version", "operation_id", "connection_id", "tool_session_id", "project_id", "denial_code", "failure_code", "attempt_count", "max_attempts", "next_retry_at", "version", "created_at", "updated_at", "queued_at", "finished_at", "result" ], "additionalProperties": false }, "ExecutionResult": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "inline" ] }, "data": {} }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "kind", "url", "expires_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "Inline normalized result or a short-lived signed download URL" }, "AttemptListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionAttempt" } } }, "required": [ "data" ], "additionalProperties": false }, "ExecutionAttempt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "execution_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "attempt_number": { "type": "integer", "exclusiveMinimum": 0 }, "outcome": { "type": "string", "enum": [ "succeeded", "failed_transient", "failed_permanent", "lost" ] }, "error_code": { "type": [ "string", "null" ], "enum": [ "provider_timeout", "provider_rate_limited", "provider_unavailable", "connection_revoked", "invalid_input", "provider_rejected", "attempt_lost", "engine_error", "retries_exhausted", null ] }, "error_message": { "type": [ "string", "null" ], "maxLength": 500 }, "started_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "finished_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "latency_ms": { "type": "integer", "minimum": 0 } }, "required": [ "id", "execution_id", "attempt_number", "outcome", "error_code", "error_message", "started_at", "finished_at", "latency_ms" ], "additionalProperties": false, "description": "Append-only attempt record; engine identifiers are deliberately not exposed" }, "CancelExecutionRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "expected_version" ], "additionalProperties": false }, "ConnectionListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "Connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "connector_version": { "type": "string", "minLength": 1, "maxLength": 40 }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "auth_method": { "type": "string", "enum": [ "oauth2", "api_key" ] }, "user_id": { "$ref": "#/components/schemas/EndUserRef" }, "is_default": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "active", "degraded", "revoked", "failed" ] }, "status_reason": { "type": [ "string", "null" ], "maxLength": 120 }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "id", "connector_id", "connector_version", "name", "auth_method", "user_id", "is_default", "status", "status_reason", "version", "created_at", "activated_at" ], "additionalProperties": false }, "EndUserRef": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 _.:@-]{0,255}$" }, "HostedAuthLink": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connect_url": { "type": "string", "maxLength": 2048, "format": "uri" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "connection_id", "connect_url", "expires_at" ], "additionalProperties": false, "description": "Hosted authorization link; direct the end user to connect_url before it expires" }, "CreateConnectionRequest": { "type": "object", "properties": { "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "user_id": { "$ref": "#/components/schemas/EndUserRef" }, "name": { "type": "string", "minLength": 2, "maxLength": 120, "pattern": "^[\\p{L}\\p{N}][\\p{L}\\p{N}\\p{Pd} _.]+$" }, "resume": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "expected_version": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "connection_id", "expected_version" ], "additionalProperties": false } }, "required": [ "connector_id", "name" ], "additionalProperties": false, "description": "Initiates hosted OAuth authorization. Optional resume renews an unactivated connection in place; account identity must match and expected_version guards concurrent attempts." }, "AuthConfigListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuthConfig" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "AuthConfig": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "mode": { "type": "string", "enum": [ "managed", "custom" ] }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "client_id_mask": { "type": "string", "maxLength": 24 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 64 }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "id", "connector_id", "mode", "name", "client_id_mask", "scopes", "status", "version", "created_at", "updated_at" ], "additionalProperties": false }, "CreateAuthConfigRequest": { "type": "object", "properties": { "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "mode": { "type": "string", "enum": [ "managed", "custom" ] }, "client_id": { "type": "string", "minLength": 4, "maxLength": 512 }, "client_secret": { "type": "string", "minLength": 8, "maxLength": 4096 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 64 } }, "required": [ "connector_id", "name" ], "additionalProperties": false, "description": "Registers a named auth configuration; a custom mode requires the tenant's OAuth client, whose secret is delivered once to the engine boundary and never echoed" }, "UpdateAuthConfigRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "exclusiveMinimum": 0 }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "expected_version" ], "additionalProperties": false }, "NetworkAttachment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "mode": { "type": "string", "enum": [ "direct", "wireguard", "openvpn" ] }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "host", "port" ], "additionalProperties": false } }, "dns_servers": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "ip" }, { "type": "string", "format": "ip" } ] }, "maxItems": 3 }, "connection_enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "provisioning", "active", "degraded", "draining", "ready_to_revoke", "revoked", "failed" ] }, "status_reason": { "type": [ "string", "null" ], "maxLength": 120 }, "desired_generation": { "type": "integer", "exclusiveMinimum": 0 }, "observed_generation": { "type": "integer", "minimum": 0 }, "active_lease_count": { "type": "integer", "minimum": 0 }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "last_health_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "id", "name", "mode", "destinations", "dns_servers", "connection_enabled", "status", "status_reason", "desired_generation", "observed_generation", "active_lease_count", "version", "last_health_at", "revoked_at", "created_at", "updated_at" ], "additionalProperties": false }, "NetworkAttachmentList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkAttachment" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "CreateNetworkAttachmentRequest": { "oneOf": [ { "type": "object", "properties": { "dns_servers": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "ip" }, { "type": "string", "format": "ip" } ] }, "maxItems": 3 }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "host", "port" ], "additionalProperties": false }, "minItems": 1, "maxItems": 64 }, "mode": { "type": "string", "enum": [ "direct" ] } }, "required": [ "name", "destinations", "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "dns_servers": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "ip" }, { "type": "string", "format": "ip" } ] }, "maxItems": 3 }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "host", "port" ], "additionalProperties": false }, "minItems": 1, "maxItems": 64 }, "mode": { "type": "string", "enum": [ "wireguard" ] }, "credential": { "type": "object", "properties": { "private_key": { "type": "string", "minLength": 32, "maxLength": 256 }, "peer_public_key": { "type": "string", "minLength": 32, "maxLength": 256 }, "preshared_key": { "type": "string", "minLength": 32, "maxLength": 256 }, "endpoint_host": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$" }, "endpoint_port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "interface_addresses": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 64 }, "minItems": 1, "maxItems": 8 } }, "required": [ "private_key", "peer_public_key", "endpoint_host", "endpoint_port", "interface_addresses" ], "additionalProperties": false } }, "required": [ "name", "destinations", "mode", "credential" ], "additionalProperties": false }, { "type": "object", "properties": { "dns_servers": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "ip" }, { "type": "string", "format": "ip" } ] }, "maxItems": 3 }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "host", "port" ], "additionalProperties": false }, "minItems": 1, "maxItems": 64 }, "mode": { "type": "string", "enum": [ "openvpn" ] }, "credential": { "type": "object", "properties": { "options": { "type": "object", "properties": { "cipher": { "type": "string", "enum": [ "AES-256-GCM", "AES-128-GCM", "CHACHA20-POLY1305" ] }, "auth": { "type": "string", "enum": [ "none", "SHA1", "SHA256", "SHA512" ] }, "tun_mtu": { "type": "integer", "minimum": 576, "maximum": 9000 }, "ping": { "type": "integer", "minimum": 0, "maximum": 3600 }, "ping_restart": { "type": "integer", "minimum": 0, "maximum": 86400 }, "connect_retry": { "type": "integer", "minimum": 1, "maximum": 300 }, "reneg_sec": { "type": "integer", "minimum": 0, "maximum": 604800 }, "persist_tun": { "type": "boolean" }, "persist_key": { "type": "boolean" }, "mute_replay_warnings": { "type": "boolean" }, "verb": { "type": "integer", "minimum": 0, "maximum": 4 } }, "additionalProperties": false }, "remote_host": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$" }, "remote_port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "protocol": { "type": "string", "enum": [ "udp", "tcp" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 16384 }, "client_certificate": { "type": "string", "minLength": 64, "maxLength": 16384 }, "client_key": { "type": "string", "minLength": 64, "maxLength": 16384 }, "tls_auth_key": { "type": "string", "minLength": 64, "maxLength": 16384 }, "tls_auth_direction": { "type": "string", "enum": [ "0", "1" ] }, "username": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\0\\r\\n]+$" }, "password": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^[^\\0\\r\\n]+$" } }, "required": [ "remote_host", "remote_port", "protocol", "ca_certificate", "client_certificate", "client_key" ], "additionalProperties": false, "not": { "required": [ "options", "tls_auth_key" ], "properties": { "options": { "required": [ "auth" ], "properties": { "auth": { "enum": [ "none" ] } } } } } } }, "required": [ "name", "destinations", "mode", "credential" ], "additionalProperties": false } ], "description": "Typed private-network configuration; arbitrary OpenVPN/WireGuard files, scripts, plugins, and routes are not accepted" }, "DiscoverPostgresDatabasesResponse": { "type": "object", "properties": { "databases": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "access": { "type": "string", "enum": [ "verified", "candidate", "denied" ] }, "connect_privilege": { "type": "boolean" } }, "required": [ "name", "access", "connect_privilege" ], "additionalProperties": false }, "maxItems": 100 }, "incomplete": { "type": "boolean" }, "seed_database": { "type": "string", "minLength": 1, "maxLength": 200 }, "error_code": { "type": [ "string", "null" ], "enum": [ "network_unavailable", "authentication_failed", "login_trigger_failed", "tls_failed", "tls_configuration_unsupported", "seed_database_unavailable", "catalog_denied", "discovery_unavailable", null ] } }, "required": [ "databases", "incomplete", "seed_database", "error_code" ], "additionalProperties": false }, "DataSourceConnection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "kind": { "type": "string", "enum": [ "postgres", "mysql", "sqlserver", "mongodb", "topic" ] }, "endpoint": { "type": "object", "properties": { "hosts": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 }, "minItems": 1, "maxItems": 20 }, "port": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 65535 }, "resource": { "type": "string", "minLength": 1, "maxLength": 200 }, "authentication": { "type": "string", "minLength": 1, "maxLength": 64 }, "tls_mode": { "type": "string", "enum": [ "require", "verify_ca", "verify_full", "mutual_tls" ] }, "custom_ca": { "type": "boolean" }, "mutual_tls": { "type": "boolean" } }, "required": [ "hosts", "port", "resource", "authentication", "tls_mode", "custom_ca", "mutual_tls" ], "additionalProperties": false }, "credential_version": { "type": "integer", "exclusiveMinimum": 0 }, "network_attachment_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "status": { "type": "string", "enum": [ "pending", "active", "degraded", "revoked", "failed" ] }, "status_reason": { "$ref": "#/components/schemas/DataSourceAttentionReason" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "id", "name", "kind", "endpoint", "credential_version", "network_attachment_id", "status", "status_reason", "created_at", "updated_at" ], "additionalProperties": false }, "DataSourceAttentionReason": { "type": [ "string", "null" ], "enum": [ "authentication_failed", "login_trigger_failed", "catalog_denied", "tls_failed", null ], "description": "Source-side condition a person must fix; set only while the connection is degraded" }, "AddDatabaseFromConnectionRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "database": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name", "database" ], "additionalProperties": false }, "DiscoverPostgresDatabasesRequest": { "type": "object", "properties": { "network_attachment_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "postgres", "sqlserver" ] }, "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "seed_database": { "type": "string", "minLength": 1, "maxLength": 200 }, "authentication": { "type": "string", "enum": [ "username_password" ] }, "credential": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "username", "password" ], "additionalProperties": false }, "tls": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "require" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "verify_ca", "verify_full" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "mutual_tls" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_key": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate", "client_certificate", "client_key" ], "additionalProperties": false } ] } }, "required": [ "kind", "host", "port", "authentication", "credential", "tls" ], "additionalProperties": false } }, "required": [ "source" ], "additionalProperties": false }, "DataSourceConnectionList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataSourceConnection" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "CreateDataSourceConnectionRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "network_attachment_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "source": { "anyOf": [ { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "database": { "type": "string", "minLength": 1, "maxLength": 200 }, "tls": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "require" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "verify_full" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate" ], "additionalProperties": false } ] }, "kind": { "type": "string", "enum": [ "sqlserver" ] }, "authentication": { "type": "string", "enum": [ "username_password" ] }, "credential": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "username", "password" ], "additionalProperties": false } }, "required": [ "host", "port", "database", "tls", "kind", "authentication", "credential" ], "additionalProperties": false }, { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "database": { "type": "string", "minLength": 1, "maxLength": 200 }, "tls": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "require" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "verify_ca", "verify_full" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "mutual_tls" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_key": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate", "client_certificate", "client_key" ], "additionalProperties": false } ] }, "kind": { "type": "string", "enum": [ "postgres" ] }, "authentication": { "type": "string", "enum": [ "username_password" ] }, "credential": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "username", "password" ], "additionalProperties": false } }, "required": [ "host", "port", "database", "tls", "kind", "authentication", "credential" ], "additionalProperties": false }, { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "database": { "type": "string", "minLength": 1, "maxLength": 200 }, "tls": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "require" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "verify_ca", "verify_full" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "mutual_tls" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_key": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate", "client_certificate", "client_key" ], "additionalProperties": false } ] }, "kind": { "type": "string", "enum": [ "mysql" ] }, "authentication": { "type": "string", "enum": [ "username_password" ] }, "credential": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "username", "password" ], "additionalProperties": false } }, "required": [ "host", "port", "database", "tls", "kind", "authentication", "credential" ], "additionalProperties": false }, { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "database": { "type": "string", "minLength": 1, "maxLength": 200 }, "tls": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "require" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "verify_ca", "verify_full" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "mutual_tls" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_key": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate", "client_certificate", "client_key" ], "additionalProperties": false } ] }, "kind": { "type": "string", "enum": [ "mongodb" ] }, "replica_set": { "type": "string", "minLength": 1, "maxLength": 200 }, "authentication": { "type": "string", "enum": [ "username_password" ] }, "credential": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "username", "password" ], "additionalProperties": false } }, "required": [ "host", "port", "database", "tls", "kind", "replica_set", "authentication", "credential" ], "additionalProperties": false }, { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "database": { "type": "string", "minLength": 1, "maxLength": 200 }, "tls": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "require" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "verify_ca", "verify_full" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "mutual_tls" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_key": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate", "client_certificate", "client_key" ], "additionalProperties": false } ] }, "kind": { "type": "string", "enum": [ "mongodb" ] }, "replica_set": { "type": "string", "minLength": 1, "maxLength": 200 }, "authentication": { "type": "string", "enum": [ "x509" ] }, "credential": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "host", "port", "database", "tls", "kind", "replica_set", "authentication", "credential" ], "additionalProperties": false }, { "type": "object", "properties": { "bootstrap_servers": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "host", "port" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20 }, "topic": { "type": "string", "minLength": 1, "maxLength": 200 }, "tls": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "require" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "verify_ca", "verify_full" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "mutual_tls" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_key": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate", "client_certificate", "client_key" ], "additionalProperties": false } ] }, "kind": { "type": "string", "enum": [ "topic" ] }, "authentication": { "type": "string", "enum": [ "sasl_scram_256" ] }, "credential": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "username", "password" ], "additionalProperties": false } }, "required": [ "bootstrap_servers", "topic", "tls", "kind", "authentication", "credential" ], "additionalProperties": false }, { "type": "object", "properties": { "bootstrap_servers": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "host", "port" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20 }, "topic": { "type": "string", "minLength": 1, "maxLength": 200 }, "tls": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "require" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "verify_ca", "verify_full" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "mutual_tls" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_key": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate", "client_certificate", "client_key" ], "additionalProperties": false } ] }, "kind": { "type": "string", "enum": [ "topic" ] }, "authentication": { "type": "string", "enum": [ "sasl_scram_512" ] }, "credential": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "username", "password" ], "additionalProperties": false } }, "required": [ "bootstrap_servers", "topic", "tls", "kind", "authentication", "credential" ], "additionalProperties": false }, { "type": "object", "properties": { "bootstrap_servers": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "host", "port" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20 }, "topic": { "type": "string", "minLength": 1, "maxLength": 200 }, "tls": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "require" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "verify_ca", "verify_full" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "mutual_tls" ] }, "ca_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_certificate": { "type": "string", "minLength": 64, "maxLength": 32768 }, "client_key": { "type": "string", "minLength": 64, "maxLength": 32768 } }, "required": [ "mode", "ca_certificate", "client_certificate", "client_key" ], "additionalProperties": false } ] }, "kind": { "type": "string", "enum": [ "topic" ] }, "authentication": { "type": "string", "enum": [ "mutual_tls" ] }, "credential": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "bootstrap_servers", "topic", "tls", "kind", "authentication", "credential" ], "additionalProperties": false } ] } }, "required": [ "name", "source" ], "additionalProperties": false, "description": "Typed source settings; raw DSNs, secret references, connector configs, and executable content are not accepted" }, "ReplaceDataSourceCredentialRequest": { "type": "object", "properties": { "credential": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 256 }, "password": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "username", "password" ], "additionalProperties": false } }, "required": [ "credential" ], "additionalProperties": false, "description": "A new username and password for a password-authenticated source; stored as the next secret version and never returned" }, "SourceSchema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "source_connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "source_technology": { "type": "string", "enum": [ "postgres", "mysql", "mongodb", "sqlserver", "topic" ] }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "entities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "key_fields": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 64 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "minLength": 1, "maxLength": 200 }, "nullable": { "type": "boolean" } }, "required": [ "name", "type", "nullable" ], "additionalProperties": false }, "minItems": 1, "maxItems": 2000 } }, "required": [ "name", "key_fields", "fields" ], "additionalProperties": false }, "maxItems": 500 }, "capabilities": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 64 }, "incomplete": { "type": "boolean" }, "compatibility": { "type": "string", "enum": [ "initial", "compatible", "breaking" ] }, "breaking_reasons": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxItems": 2000 }, "predecessor_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "id", "source_connection_id", "source_technology", "version", "hash", "entities", "capabilities", "incomplete", "compatibility", "breaking_reasons", "predecessor_id", "created_at" ], "additionalProperties": false }, "ProviderSchema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connector_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "entity": { "type": "string", "minLength": 1, "maxLength": 80 }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "key_fields": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "provider_name": { "type": "string", "minLength": 1 }, "definition": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "provider_name", "definition" ], "additionalProperties": false }, "minItems": 1 }, "predecessor_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "id", "connection_id", "connector_id", "entity", "version", "hash", "key_fields", "fields", "predecessor_id", "created_at" ], "additionalProperties": false }, "ToolSessionWithMcp": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connection_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "user_id": { "$ref": "#/components/schemas/EndUserRef" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/SessionTool" } }, "disabled_tools": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{1,239}$" } }, "connections": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "alias": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64 } }, "required": [ "connection_id", "alias" ], "additionalProperties": false } } }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "max_calls": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "calls_used": { "type": "integer", "minimum": 0 }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "mcp_url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "id", "connection_id", "user_id", "status", "tools", "disabled_tools", "connections", "expires_at", "max_calls", "calls_used", "version", "created_at", "updated_at", "mcp_url" ], "additionalProperties": false }, "SessionTool": { "type": "object", "properties": { "tool_id": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{1,239}$" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "connector_version": { "type": "string", "minLength": 1, "maxLength": 40 }, "operation_id": { "type": "string", "minLength": 1, "maxLength": 160 }, "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" } }, "required": [ "tool_id", "connector_id", "connector_version", "operation_id", "connection_id" ], "additionalProperties": false }, "CreateToolSessionRequest": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "user_id": { "$ref": "#/components/schemas/EndUserRef" }, "tool_allowlist": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{1,239}$" }, "minItems": 1, "maxItems": 200 }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 86400 }, "max_calls": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000 } }, "additionalProperties": false, "anyOf": [ { "required": [ "connection_id" ] }, { "required": [ "user_id" ] } ], "description": "Creates a tool session. With a pinned connection the snapshot derives from connection ∩ catalog ∩ policy ∩ allowlist and is immutable afterwards; without one the session starts empty and fills as accounts are connected to it" }, "ToolSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connection_id": { "type": [ "string", "null" ], "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "user_id": { "$ref": "#/components/schemas/EndUserRef" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/SessionTool" } }, "disabled_tools": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{1,239}$" } }, "connections": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "alias": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64 } }, "required": [ "connection_id", "alias" ], "additionalProperties": false } } }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "max_calls": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "calls_used": { "type": "integer", "minimum": 0 }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "id", "connection_id", "user_id", "status", "tools", "disabled_tools", "connections", "expires_at", "max_calls", "calls_used", "version", "created_at", "updated_at" ], "additionalProperties": false }, "PatchToolSessionRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "exclusiveMinimum": 0 }, "disable": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{1,239}$" }, "minItems": 1, "maxItems": 200 }, "enable": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{1,239}$" }, "minItems": 1, "maxItems": 200 } }, "required": [ "expected_version" ], "additionalProperties": false, "description": "Bounded session mutation: enable/disable tools within the immutable snapshot, CAS-guarded by expected_version" }, "SessionToolListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SessionToolDetail" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400 } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "SessionToolDetail": { "type": "object", "properties": { "tool_id": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{1,239}$" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "connector_version": { "type": "string", "minLength": 1, "maxLength": 40 }, "operation_id": { "type": "string", "minLength": 1, "maxLength": 160 }, "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "input_schema": {} }, "required": [ "tool_id", "connector_id", "connector_version", "operation_id", "connection_id", "display_name", "description" ], "additionalProperties": false }, "SyncDeliveryAuthority": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "context4OrganizationId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,200}$" }, "workspaceId": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "syncId": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "entity": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }, "resourceKey": { "type": "string", "minLength": 1, "maxLength": 500 }, "deliveryGrants": { "type": "array", "items": { "type": "object", "properties": { "deliveryGrantId": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "deliveryGeneration": { "type": "integer", "exclusiveMinimum": 0 }, "state": { "type": "string", "enum": [ "active", "retiring", "revoked" ] }, "retiringExpiresAt": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "revocationBarriers": { "type": "array", "items": { "type": "object", "properties": { "partition": { "type": "integer", "minimum": 0 }, "offset": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$" } }, "required": [ "partition", "offset" ], "additionalProperties": false }, "maxItems": 1024 } }, "required": [ "deliveryGrantId", "deliveryGeneration", "state", "retiringExpiresAt", "revocationBarriers" ], "additionalProperties": false }, "minItems": 1, "maxItems": 8 }, "sourceEpoch": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "sourceEpochTransition": { "type": "string", "enum": [ "continuation", "replacement-snapshot", "incompatible-reset" ] }, "authorityRevision": { "type": "integer", "exclusiveMinimum": 0 }, "active": { "type": "boolean" } }, "required": [ "schemaVersion", "context4OrganizationId", "workspaceId", "syncId", "entity", "resourceKey", "deliveryGrants", "sourceEpoch", "sourceEpochTransition", "authorityRevision", "active" ], "additionalProperties": false }, "Sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "source_kind": { "type": "string", "enum": [ "api_poll", "database_cdc", "database_poll", "topic" ] }, "database_poll": { "type": [ "object", "null" ], "properties": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "table": { "type": "string", "minLength": 1, "maxLength": 128 }, "columns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 256 }, "primary_key": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 16 }, "mode": { "type": "string", "enum": [ "full_scan", "rowversion", "timestamp" ] }, "watermark_column": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "full_reconciliation_minutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "timestamp_overlap_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "deletion_policy": { "type": "string", "enum": [ "preserve", "confirm_missing" ] }, "config_revision": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "schema", "table", "columns", "primary_key", "mode", "watermark_column", "full_reconciliation_minutes", "timestamp_overlap_seconds", "deletion_policy", "config_revision" ], "additionalProperties": false }, "entity": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }, "strategy": { "type": "string", "enum": [ "incremental", "snapshot-diff" ] }, "schedule_minutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "schedule_clamped": { "type": "boolean" }, "requested_schedule_minutes": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10080 }, "status": { "type": "string", "enum": [ "enabled", "paused", "deleted" ] }, "source_health": { "type": [ "object", "null" ], "properties": { "phase": { "type": "string", "enum": [ "gateway_connecting", "source_connecting", "snapshotting", "streaming", "paused", "failed" ] }, "classified_error": { "type": [ "string", "null" ], "maxLength": 120 }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "artifacts": { "type": [ "object", "null" ], "properties": { "state": { "type": "string", "minLength": 1, "maxLength": 16, "description": "One of `held`, `released`, `orphaned`, `absent`.", "example": "held" }, "since": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "state", "since" ], "additionalProperties": false, "description": "The PostgreSQL replication slot and publication this CDC sync holds on its source, and since when it is in that state: `held`; `released` — the sync stayed paused past the pause limit or failed past the failed-slot grace, so the slot was dropped and the next start takes a fresh snapshot; `orphaned` — a release gave up and the source's DBA must drop the slot; `absent` — nothing was left to release. Null for a source that holds none." } }, "required": [ "phase", "classified_error", "updated_at", "artifacts" ], "additionalProperties": false }, "source_attention": { "$ref": "#/components/schemas/DataSourceAttentionReason" }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "id", "connector_id", "connection_id", "source_kind", "entity", "strategy", "schedule_minutes", "schedule_clamped", "requested_schedule_minutes", "status", "source_health", "last_run_at", "next_run_at", "created_at", "updated_at" ], "additionalProperties": false }, "SyncList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sync" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "SyncTestFire": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "payload": { "type": "object", "additionalProperties": {} } }, "required": [ "external_id", "payload" ], "additionalProperties": false } }, "estimated_total": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "records", "estimated_total" ], "additionalProperties": false }, "SyncRunList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SyncRun" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "SyncRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "sync_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "kind": { "type": "string", "enum": [ "backfill", "incremental", "manual" ] }, "status": { "type": "string", "enum": [ "planned", "running", "deferred", "completed", "failed" ] }, "fetched": { "type": "integer", "minimum": 0 }, "created": { "type": "integer", "minimum": 0 }, "updated": { "type": "integer", "minimum": 0 }, "deleted": { "type": "integer", "minimum": 0 }, "error_code": { "type": [ "string", "null" ], "maxLength": 120 }, "backoff_reason": { "type": [ "string", "null" ], "maxLength": 200 }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "duration_ms": { "type": [ "integer", "null" ], "minimum": 0 }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "id", "sync_id", "kind", "status", "fetched", "created", "updated", "deleted", "error_code", "backoff_reason", "started_at", "completed_at", "duration_ms", "created_at" ], "additionalProperties": false }, "SyncRecordList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SyncRecord" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "SyncRecord": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "entity": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }, "change_type": { "type": "string", "enum": [ "created", "updated", "deleted" ] }, "mod_cursor": { "type": "string", "minLength": 1, "maxLength": 64 }, "payload": { "type": [ "object", "null" ], "additionalProperties": {} }, "run_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "recorded_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" } }, "required": [ "external_id", "entity", "change_type", "mod_cursor", "payload", "run_id", "recorded_at" ], "additionalProperties": false }, "SyncReplay": { "type": "object", "properties": { "replayed": { "type": "integer", "minimum": 0 } }, "required": [ "replayed" ], "additionalProperties": false }, "SyncableEntityList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "strategy": { "type": "string", "enum": [ "incremental", "snapshot-diff" ] }, "default_schedule_minutes": { "type": "integer", "minimum": 1, "maximum": 10080 } }, "required": [ "key", "title", "strategy", "default_schedule_minutes" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "SyncDeliveryCapabilities": { "type": "object", "properties": { "channel_version": { "type": "string", "minLength": 1, "maxLength": 40 }, "envelope_schema_versions": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1 }, "max_payload_bytes": { "type": "integer", "minimum": 1 }, "max_envelope_bytes": { "type": "integer", "minimum": 1 }, "max_key_bytes": { "type": "integer", "minimum": 1 }, "payload_measurement": { "type": "string", "enum": [ "utf8-json" ] }, "delete_semantics": { "type": "string", "enum": [ "logical-delete-null-payload", "two-step-logical-delete-then-tombstone" ] }, "retraction": { "type": "object", "properties": { "header": { "type": "string", "minLength": 1, "maxLength": 80 }, "marker": { "type": "string", "minLength": 1, "maxLength": 80 }, "grace_ms": { "type": "integer", "minimum": 1 }, "min_compaction_lag_ms": { "type": "integer", "minimum": 1 }, "delete_retention_ms": { "type": "integer", "minimum": 1 } }, "required": [ "header", "marker", "grace_ms", "min_compaction_lag_ms", "delete_retention_ms" ], "additionalProperties": false }, "oversized_record_code": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "channel_version", "envelope_schema_versions", "max_payload_bytes", "max_envelope_bytes", "max_key_bytes", "payload_measurement", "delete_semantics", "retraction", "oversized_record_code" ], "additionalProperties": false }, "SyncExportSession": { "type": "object", "properties": { "export_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "organization_id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,200}$" }, "workspace_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "schema_fingerprint": { "type": [ "string", "null" ], "pattern": "^sha256:[a-f0-9]{64}$" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "range": { "type": "object", "properties": { "after_cursor": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,18})$" }, "through_cursor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$" } }, "required": [ "after_cursor", "through_cursor" ], "additionalProperties": false }, "sync_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "entity": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }, "state": { "type": "string", "enum": [ "preparing", "running", "complete", "range_expired", "archive_unavailable", "digest_mismatch", "cancelled", "failed" ] }, "frontier": { "type": "object", "properties": { "mod_cursor": { "type": "string", "minLength": 1, "maxLength": 20 }, "captured_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "source_epoch": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" } }, "required": [ "mod_cursor", "captured_at", "source_epoch" ], "additionalProperties": false }, "publication_barrier": { "type": "array", "items": { "type": "object", "properties": { "partition": { "type": "integer", "minimum": 0 }, "offset": { "type": "string", "minLength": 1, "maxLength": 20 } }, "required": [ "partition", "offset" ], "additionalProperties": false } }, "publication_channel": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,248}$" }, "progress": { "type": "object", "properties": { "records": { "type": "integer", "minimum": 0 }, "encoded_bytes": { "type": "integer", "minimum": 0 } }, "required": [ "records", "encoded_bytes" ], "additionalProperties": false }, "record_count": { "type": [ "integer", "null" ], "minimum": 0 }, "digest": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 71 }, "terminal_reason": { "type": [ "string", "null" ], "maxLength": 200 }, "delivery": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bounded-replay-topic" ] }, "channel": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,248}$" }, "export_key": { "type": "string", "minLength": 1, "maxLength": 200 }, "delivery_generation": { "type": "integer", "exclusiveMinimum": 0 }, "state": { "type": "string", "enum": [ "pending", "publishing", "complete", "failed", "cancelled" ] }, "records": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$" }, "terminal_positions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "partition": { "type": "integer", "minimum": 0 }, "offset": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } }, "required": [ "partition", "offset" ], "additionalProperties": false }, "minItems": 1 }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "error": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "kind", "channel", "export_key", "delivery_generation", "state", "records", "terminal_positions", "completed_at", "updated_at", "error" ], "additionalProperties": false }, "parts": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "after_cursor": { "type": "string", "minLength": 1, "maxLength": 20 }, "through_cursor": { "type": "string", "minLength": 1, "maxLength": 20 }, "records": { "type": "integer", "minimum": 1 }, "encoded_bytes": { "type": "integer", "minimum": 1 }, "digest": { "type": "string", "minLength": 1, "maxLength": 71 }, "download_url": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 4096 } }, "required": [ "index", "after_cursor", "through_cursor", "records", "encoded_bytes", "digest", "download_url" ], "additionalProperties": false } } }, "required": [ "export_id", "sync_id", "entity", "state", "frontier", "publication_barrier", "progress", "record_count", "digest", "terminal_reason", "parts" ], "additionalProperties": false }, "SyncProviderListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "key", "display_name" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "EndpointListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointSummary" } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 400, "description": "Cursor for the next page; null when exhausted" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "EndpointSummary": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:GET|POST|PUT|PATCH|DELETE|HEAD) \\/[\\x21-\\x7e]{0,240}$", "example": "GET /api/v4/leads/{id}" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "group": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The vendor's own grouping of the endpoint (its spec tag or resource)", "example": "leads" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "path": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^\\/", "example": "/api/v4/leads/{id}" }, "summary": { "type": [ "string", "null" ], "maxLength": 2000 }, "call_url": { "type": "string", "minLength": 1, "maxLength": 600, "description": "The mirror URL that calls this endpoint: `/v1/api/{connectorId}` followed by the vendor path", "example": "/v1/api/amocrm/api/v4/leads/{id}" }, "risk": { "type": "string", "enum": [ "read", "write", "destructive", "external_send" ], "description": "What calling it does to the world, as a floor: read, write, destructive or external_send (reaches a person outside the vendor)" }, "sensitive": { "type": "boolean", "description": "Its schemas name credentials or personal data (a floor)" }, "idempotent": { "type": "boolean" }, "paging_kind": { "type": [ "string", "null" ], "enum": [ "page", "offset", "cursor", "next-link", "header-cursor", "rpc-start", "relay", null ], "description": "How a listing pages, or null when pages cannot be collected from it" }, "descriptor_digest": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the endpoint's contract (method, path, schemas, risk, idempotency — not its paging or summary); null only for a row seeded before descriptors existed", "example": "089fed2ebbff74aa8cd059e02cedb06f5fa5044a8e86ff7b457e75a90b8341fa" }, "removed_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z", "description": "When a lock regeneration dropped the endpoint; null while it is live. A removed endpoint is listed only with `include_removed=true`" } }, "required": [ "id", "connector_id", "group", "method", "path", "summary", "call_url" ], "additionalProperties": false }, "EndpointDetail": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:GET|POST|PUT|PATCH|DELETE|HEAD) \\/[\\x21-\\x7e]{0,240}$", "example": "GET /api/v4/leads/{id}" }, "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "group": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The vendor's own grouping of the endpoint (its spec tag or resource)", "example": "leads" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "path": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^\\/", "example": "/api/v4/leads/{id}" }, "summary": { "type": [ "string", "null" ], "maxLength": 2000 }, "call_url": { "type": "string", "minLength": 1, "maxLength": 600, "description": "The mirror URL that calls this endpoint: `/v1/api/{connectorId}` followed by the vendor path", "example": "/v1/api/amocrm/api/v4/leads/{id}" }, "risk": { "type": "string", "enum": [ "read", "write", "destructive", "external_send" ], "description": "What calling it does to the world, as a floor: read, write, destructive or external_send (reaches a person outside the vendor)" }, "sensitive": { "type": "boolean", "description": "Its schemas name credentials or personal data (a floor)" }, "idempotent": { "type": "boolean" }, "paging_kind": { "type": [ "string", "null" ], "enum": [ "page", "offset", "cursor", "next-link", "header-cursor", "rpc-start", "relay", null ], "description": "How a listing pages, or null when pages cannot be collected from it" }, "descriptor_digest": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the endpoint's contract (method, path, schemas, risk, idempotency — not its paging or summary); null only for a row seeded before descriptors existed", "example": "089fed2ebbff74aa8cd059e02cedb06f5fa5044a8e86ff7b457e75a90b8341fa" }, "removed_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-16T12:00:00.000Z", "description": "When a lock regeneration dropped the endpoint; null while it is live. A removed endpoint is listed only with `include_removed=true`" }, "input_schema": { "description": "JSON Schema of the call input: an object with optional `path`, `query`, `header` and `body` members, self-contained (`$defs` included)" }, "output_schema": {}, "paging": { "$ref": "#/components/schemas/PagingDescriptor" } }, "required": [ "id", "connector_id", "group", "method", "path", "summary", "call_url" ], "additionalProperties": false, "description": "One raw endpoint with its input and (when published) output schema, and its paging descriptor" }, "PagingDescriptor": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "enum": [ "page", "offset", "cursor", "next-link", "header-cursor", "rpc-start", "relay" ] }, "records": { "type": "string", "maxLength": 500, "description": "Pointer to the records array in the output; `\"\"` is the whole document", "example": "/_embedded/leads" }, "max_page_size": { "type": "integer", "exclusiveMinimum": 0 }, "inputs": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500, "description": "RFC 6901 JSON pointer into the endpoint's input or output document", "example": "/query/page" }, "description": "Input pointers by role: page, size, cursor, offset, start, first, after" }, "next": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Where the next page is named: output pointers by role (link, cursor, end_cursor, has_next_page) or `header`, a response header name" } }, "required": [ "kind", "records", "max_page_size", "inputs" ], "additionalProperties": false }, "ConnectorOpenApiDocument": { "type": "object", "properties": { "openapi": { "type": "string", "enum": [ "3.1.0" ] }, "info": { "type": "object", "additionalProperties": {} }, "servers": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "paths": { "type": "object", "additionalProperties": {} }, "components": { "type": "object", "additionalProperties": {} } }, "required": [ "openapi", "info", "servers", "paths", "components" ], "additionalProperties": {} }, "EndpointSearchResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointSearchItem" } }, "scope": { "type": "object", "properties": { "connectors": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "description": "The connectors the search ran over: those of the caller's usable connections, narrowed by `connectors`. Empty when nothing is usable — then `items` is empty too, never an error" }, "index": { "type": "string", "enum": [ "ratel", "ilike" ] } }, "required": [ "connectors", "index" ], "additionalProperties": false } }, "required": [ "items", "scope" ], "additionalProperties": false }, "EndpointSearchItem": { "type": "object", "properties": { "connector_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "endpoint_id": { "type": "string", "pattern": "^(?:GET|POST|PUT|PATCH|DELETE|HEAD) \\/[\\x21-\\x7e]{0,240}$", "example": "GET /api/v4/leads/{id}" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "path": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^\\/", "example": "/api/v4/leads/{id}" }, "summary": { "type": [ "string", "null" ], "maxLength": 2000 }, "group": { "type": "string", "minLength": 1, "maxLength": 64 }, "risk": { "type": "string", "enum": [ "read", "write", "destructive", "external_send" ] }, "sensitive": { "type": "boolean" }, "idempotent": { "type": "boolean" }, "paging_kind": { "type": [ "string", "null" ], "enum": [ "page", "offset", "cursor", "next-link", "header-cursor", "rpc-start", "relay", null ] }, "descriptor_digest": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the endpoint's contract (method, path, schemas, risk, idempotency — not its paging or summary); null only for a row seeded before descriptors existed", "example": "089fed2ebbff74aa8cd059e02cedb06f5fa5044a8e86ff7b457e75a90b8341fa" }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Relevance relative to the best hit of this answer: the top hit is 1, the rest in (0, 1]; a fallback answer scores every hit 1" } }, "required": [ "connector_id", "endpoint_id", "method", "path", "summary", "group", "risk", "sensitive", "idempotent", "paging_kind", "descriptor_digest", "score" ], "additionalProperties": false }, "EndpointSearchRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Free text, Russian or English", "example": "list the labels of a repository" }, "connectors": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "maxItems": 50, "description": "Narrows the scope to these connectors; a connector the caller has no usable connection for is dropped, never added" }, "borrowers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 200, "description": "The principals whose connections this search may use (exact `end_user_ref` match, never widened). Omitted: every active connection of the API key's workspace", "example": [ "ws_a1b2c3:u_d4e5f6", "ws_a1b2c3:a_workspace" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, "required": [ "query" ], "additionalProperties": false }, "ConnectorApiBody": {} }, "parameters": {} }, "paths": { "/v1/tools": { "get": { "operationId": "listTools", "summary": "List published tools", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": false, "name": "connector_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 20)" }, "required": false, "description": "Page size (1-100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Published tools (flattened connector actions)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolListResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tools/{toolId}": { "get": { "operationId": "getTool", "summary": "Get one tool with its JSON schemas", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}\\.[a-z0-9][a-z0-9_.]{1,78}$", "example": "bitrix24.contact.create" }, "required": true, "name": "toolId", "in": "path" } ], "responses": { "200": { "description": "Tool detail with pinned input/output schemas", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDetail" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/identity": { "get": { "operationId": "getIdentity", "summary": "Get the authenticated credential's tenant", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Verified organization and workspace; no credential material", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicIdentity" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/executions": { "post": { "operationId": "createExecution", "summary": "Create an execution (asynchronous, idempotent)", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExecutionRequest" } } } }, "responses": { "202": { "description": "Execution accepted (queued) or persisted as rejected with a denial code; poll the Location header", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } }, "Location": { "description": "Resource location (/v1/executions/{executionId})", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden, session_expired, session_revoked, session_call_budget_exhausted)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (idempotency_conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "listExecutions", "summary": "List executions", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "requested", "queued", "running", "retrying", "succeeded", "failed", "rejected", "cancelled" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": false, "name": "connector_id", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ExecutionEndUserRef" }, "required": false, "name": "user_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-07-16T12:00:00.000Z" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 20)" }, "required": false, "description": "Page size (1-100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Executions ordered by creation time (descending)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionListResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/executions/{executionId}": { "get": { "operationId": "getExecution", "summary": "Get one execution with its result", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "executionId", "in": "path" } ], "responses": { "200": { "description": "Execution view; terminal successes include the result", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionWithResult" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/executions/{executionId}/attempts": { "get": { "operationId": "listExecutionAttempts", "summary": "List execution attempts", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "executionId", "in": "path" } ], "responses": { "200": { "description": "Append-only attempt records", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttemptListResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/executions/{executionId}/cancel": { "post": { "operationId": "cancelExecution", "summary": "Cancel a queued execution", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "executionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelExecutionRequest" } } } }, "responses": { "200": { "description": "The cancelled execution", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict, execution_not_cancellable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections": { "get": { "operationId": "listConnections", "summary": "List connections", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "pending", "active", "degraded", "revoked", "failed" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "$ref": "#/components/schemas/EndUserRef" }, "required": false, "name": "user_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 20)" }, "required": false, "description": "Page size (1-100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Connections in the key's workspace", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionListResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createConnection", "summary": "Initiate a connection (hosted auth link)", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectionRequest" } } } }, "responses": { "201": { "description": "Hosted authorization link for the end user", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedAuthLink" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections/{connectionId}": { "get": { "operationId": "getConnection", "summary": "Get one connection", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "connectionId", "in": "path" } ], "responses": { "200": { "description": "Connection view (engine-free)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/auth-configs": { "get": { "operationId": "listAuthConfigs", "summary": "List auth configurations", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": false, "name": "connector_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 20)" }, "required": false, "description": "Page size (1-100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Auth configurations in the key's workspace", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthConfigListResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createAuthConfig", "summary": "Create an auth configuration", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAuthConfigRequest" } } } }, "responses": { "201": { "description": "The created auth configuration", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthConfig" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/auth-configs/{authConfigId}": { "get": { "operationId": "getAuthConfig", "summary": "Get one auth configuration", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "authConfigId", "in": "path" } ], "responses": { "200": { "description": "Auth configuration (secret-free)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthConfig" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateAuthConfig", "summary": "Update an auth configuration", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "authConfigId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAuthConfigRequest" } } } }, "responses": { "200": { "description": "The updated auth configuration", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthConfig" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteAuthConfig", "summary": "Delete an auth configuration", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "authConfigId", "in": "path" } ], "responses": { "204": { "description": "Deleted", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/network-attachments/{networkAttachmentId}/connectivity": { "patch": { "operationId": "setNetworkAttachmentConnectivity", "summary": "Disconnect or reconnect a private-network attachment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "networkAttachmentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "type": "integer", "exclusiveMinimum": 0 }, "enabled": { "type": "boolean" } }, "required": [ "expected_version", "enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Persisted connectivity intent; status reason reports operator acknowledgement", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkAttachment" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/network-attachments": { "get": { "operationId": "listNetworkAttachments", "summary": "List private-network attachments", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 20)" }, "required": false, "description": "Page size (1-100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Tenant-scoped secret-free attachment views", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkAttachmentList" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createNetworkAttachment", "summary": "Create a typed direct, WireGuard, or OpenVPN attachment", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNetworkAttachmentRequest" } } } }, "responses": { "201": { "description": "Created attachment; private credentials are never returned", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkAttachment" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/network-attachments/{networkAttachmentId}": { "get": { "operationId": "getNetworkAttachment", "summary": "Get one private-network attachment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "networkAttachmentId", "in": "path" } ], "responses": { "200": { "description": "Secret-free attachment health and desired state", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkAttachment" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateNetworkAttachment", "summary": "Replace the approved destination policy", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "networkAttachmentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dns_servers": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "ip" }, { "type": "string", "format": "ip" } ] }, "maxItems": 3 }, "expected_version": { "type": "integer", "exclusiveMinimum": 0 }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "required": [ "host", "port" ], "additionalProperties": false }, "minItems": 1, "maxItems": 64 } }, "required": [ "expected_version", "destinations" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated desired generation", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkAttachment" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "revokeNetworkAttachment", "summary": "Drain and revoke a private-network attachment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "networkAttachmentId", "in": "path" }, { "schema": { "type": "integer", "exclusiveMinimum": 0 }, "required": true, "name": "expected_version", "in": "query" } ], "responses": { "200": { "description": "Draining or ready-to-revoke attachment", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkAttachment" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/data-source-connections/{dataSourceConnectionId}/discover-databases": { "post": { "operationId": "discoverSavedDatabases", "summary": "Discover databases using a stored, tenant-owned connection", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "dataSourceConnectionId", "in": "path" } ], "responses": { "200": { "description": "Bounded database catalog without returning credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverPostgresDatabasesResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/data-source-connections/{dataSourceConnectionId}/databases": { "post": { "operationId": "addDatabaseFromConnection", "summary": "Add a database using the stored server credential", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome", "schema": { "type": "string" } }, { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "dataSourceConnectionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDatabaseFromConnectionRequest" } } } }, "responses": { "201": { "description": "Independent database connection with its own revocable secret", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceConnection" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/data-source-connections/discover-databases": { "post": { "operationId": "discoverPostgresDatabases", "summary": "Discover PostgreSQL or SQL Server databases before creating a source", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverPostgresDatabasesRequest" } } } }, "responses": { "200": { "description": "Bounded database catalog with explicit session evidence", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverPostgresDatabasesResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/data-source-connections": { "get": { "operationId": "listDataSourceConnections", "summary": "List database and topic source connections", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 20)" }, "required": false, "description": "Page size (1-100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Tenant-scoped secret-free source views", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceConnectionList" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createDataSourceConnection", "summary": "Create a typed database or topic source connection", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataSourceConnectionRequest" } } } }, "responses": { "201": { "description": "Created source; credentials are never returned", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceConnection" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/data-source-connections/{dataSourceConnectionId}": { "get": { "operationId": "getDataSourceConnection", "summary": "Get one database or topic source connection", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "dataSourceConnectionId", "in": "path" } ], "responses": { "200": { "description": "Secret-free source connection view", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceConnection" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "revokeDataSourceConnection", "summary": "Revoke a database or topic source connection", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "dataSourceConnectionId", "in": "path" } ], "responses": { "200": { "description": "Revoked source connection", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceConnection" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/data-source-connections/{dataSourceConnectionId}/credential": { "post": { "operationId": "replaceDataSourceCredential", "summary": "Replace the password credential of a source connection", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "dataSourceConnectionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceDataSourceCredentialRequest" } } } }, "responses": { "200": { "description": "Source with the new credential version; a degraded source returns to pending until an inspection succeeds", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceConnection" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/data-source-connections/{dataSourceConnectionId}/schema": { "get": { "operationId": "getDataSourceSchema", "summary": "Get the latest discovered source schema", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "dataSourceConnectionId", "in": "path" } ], "responses": { "200": { "description": "Latest tenant-scoped source schema", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceSchema" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "discoverDataSourceSchema", "summary": "Inspect a source, persist its schema, and activate the connection", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome", "schema": { "type": "string" } }, { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "dataSourceConnectionId", "in": "path" } ], "responses": { "200": { "description": "Discovered immutable source schema version", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceSchema" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connections/{connectionId}/schemas/{entity}": { "get": { "operationId": "getProviderSchema", "summary": "Read the latest discovered provider entity schema", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "connectionId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": true, "name": "entity", "in": "path" } ], "responses": { "200": { "description": "Latest tenant-scoped provider schema", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSchema" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "discoverProviderSchema", "summary": "Discover and persist provider entity metadata", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome", "schema": { "type": "string" } }, { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "connectionId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": true, "name": "entity", "in": "path" } ], "responses": { "200": { "description": "Immutable provider schema revision", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSchema" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tool-sessions": { "post": { "operationId": "createToolSession", "summary": "Create a tool session (returns the per-session MCP URL)", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateToolSessionRequest" } } } }, "responses": { "201": { "description": "The created session with its per-session MCP URL", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSessionWithMcp" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tool-sessions/{toolSessionId}": { "get": { "operationId": "getToolSession", "summary": "Get one tool session with its configuration", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "toolSessionId", "in": "path" } ], "responses": { "200": { "description": "The session view including its configuration", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSession" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "patchToolSession", "summary": "Update session tool enablement (CAS)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "toolSessionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchToolSessionRequest" } } } }, "responses": { "200": { "description": "The updated session view", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSession" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tool-sessions/{toolSessionId}/tools": { "get": { "operationId": "listToolSessionTools", "summary": "Session-scoped tool discovery (pinned snapshot, exposed tools only)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "toolSessionId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 20)" }, "required": false, "description": "Page size (1-100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "The session's exposed tools with pinned schemas", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionToolListResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs/{syncId}/delivery-authority": { "get": { "operationId": "getSyncDeliveryAuthority", "summary": "Read the tenant-scoped delivery grant fence for a sync resource", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }, "required": true, "name": "entity", "in": "query" } ], "responses": { "200": { "description": "Persisted delivery grants and source lineage without credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncDeliveryAuthority" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs": { "post": { "operationId": "createSync", "summary": "Create a sync binding a connection to a syncable entity", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required when source_kind is database_poll; retries with the same key and payload return the original sync. Optional for other source kinds.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "source_kind": { "type": "string", "enum": [ "api_poll", "database_cdc", "database_poll", "topic" ] }, "database_poll": { "type": "object", "properties": { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "table": { "type": "string", "minLength": 1, "maxLength": 128 }, "columns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 256 }, "primary_key": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 16 }, "mode": { "type": "string", "enum": [ "full_scan", "rowversion", "timestamp" ] }, "watermark_column": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "full_reconciliation_minutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "timestamp_overlap_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "deletion_policy": { "type": "string", "enum": [ "preserve", "confirm_missing" ] } }, "required": [ "schema", "table", "columns", "primary_key" ], "additionalProperties": false }, "entity": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }, "schedule_minutes": { "type": "integer", "minimum": 1, "maximum": 10080 } }, "required": [ "connection_id", "entity" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The created sync; acquisition and initial loading follow the provider capabilities", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sync" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited, quota_exceeded)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "listSyncs", "summary": "List syncs in the workspace", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 25)" }, "required": false, "description": "Page size (1-100, default 25)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": false, "name": "connection_id", "in": "query" } ], "responses": { "200": { "description": "One page of syncs with the continuation cursor", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncList" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs/{syncId}": { "get": { "operationId": "getSync", "summary": "Get one sync", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" } ], "responses": { "200": { "description": "The sync view", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sync" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "patchSync", "summary": "Pause, resume, or update the schedule of a sync", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "pause", "resume" ] } }, "required": [ "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "update_schedule" ] }, "schedule_minutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "full_reconciliation_minutes": { "type": "integer", "minimum": 1, "maximum": 10080 }, "deletion_policy": { "type": "string", "enum": [ "preserve" ] }, "expected_config_revision": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "action", "schedule_minutes", "expected_config_revision" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "The updated sync view", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sync" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteSync", "summary": "Delete a sync (record history stays pullable)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" } ], "responses": { "200": { "description": "The deleted sync view", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sync" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs/test-fire": { "post": { "operationId": "testFireSync", "summary": "Synchronously probe a bounded record sample without persisting anything", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "entity": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }, "sample_limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "connection_id", "entity" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Normalized sample records plus the estimated total volume", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncTestFire" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable, provider_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs/{syncId}/trigger": { "post": { "operationId": "triggerSyncRun", "summary": "Enqueue a manual run", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required when the sync source_kind is database_poll; retries with the same key return the original run. Optional for other source kinds.", "schema": { "type": "string" } }, { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" } ], "responses": { "202": { "description": "The sync view with the planned run enqueued", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sync" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict). The source does not support a manual refresh, or a run is already active", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs/{syncId}/runs": { "get": { "operationId": "listSyncRuns", "summary": "Run history with per-change-type counters and error causes", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 25)" }, "required": false, "description": "Page size (1-100, default 25)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "One page of runs with the continuation cursor", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRunList" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs/{syncId}/records": { "get": { "operationId": "pullSyncRecords", "summary": "Cursor-paged record change stream (the pull door onto the broker stream)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 25)" }, "required": false, "description": "Page size (1-100, default 25)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "One page of record changes ordered by modification cursor", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRecordList" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs/{syncId}/replay": { "post": { "operationId": "replaySyncRecords", "summary": "Replay dead-lettered record deliveries for a sync", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" } ], "responses": { "200": { "description": "The number of records reset for republication", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncReplay" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connectors/{connectorId}/syncable-entities": { "get": { "operationId": "listSyncableEntities", "summary": "Entities the catalog declares syncable for a connector", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": true, "name": "connectorId", "in": "path" } ], "responses": { "200": { "description": "Syncable entities with strategy and default schedule", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncableEntityList" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/sync-delivery-capabilities": { "get": { "operationId": "getSyncDeliveryCapabilities", "summary": "Delivery limits and semantics a consumer must satisfy", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Byte limits, envelope versions and delete semantics this deployment honours", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncDeliveryCapabilities" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs/{syncId}/exports": { "post": { "operationId": "createSyncExport", "summary": "Open an immutable historical export over a captured frontier", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "file", "bounded-replay-topic" ] }, "entity": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200 }, "range": { "type": "object", "properties": { "after_cursor": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,18})$" }, "through_cursor": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,18})$" } }, "required": [ "after_cursor", "through_cursor" ], "additionalProperties": false } }, "required": [ "entity", "idempotency_key" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Export session with its captured frontier and publication barrier", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncExportSession" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable, provider_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs/{syncId}/exports/{exportId}/cancel": { "post": { "operationId": "cancelSyncExport", "summary": "Request cancellation of a running export", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "exportId", "in": "path" } ], "responses": { "202": { "description": "Cancellation recorded; the session reaches `cancelled` once the runner stops", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncExportSession" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/syncs/{syncId}/exports/{exportId}": { "get": { "operationId": "getSyncExport", "summary": "Read an export session's state and progress", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "syncId", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "exportId", "in": "path" } ], "responses": { "200": { "description": "Export session state, progress and terminal outcome", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncExportSession" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/sync-providers": { "get": { "operationId": "listSyncProviders", "summary": "List published Sync providers", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 20)" }, "required": false, "description": "Page size (1-100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Published providers with Sync entities; empty pages may have a continuation cursor", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncProviderListResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/provider-event-types": { "get": { "operationId": "listProviderEventTypes", "summary": "List supported provider notification types and fields", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Provider event catalog", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "connector_id": { "type": "string" }, "entity": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "array", "items": { "type": "string" } }, "field_types": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "string", "number", "boolean" ] } }, "hydration_available": { "type": "boolean" } }, "required": [ "connector_id", "entity", "event_types", "fields", "field_types", "hydration_available" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/provider-event-subscriptions": { "post": { "operationId": "subscribeProviderEvents", "summary": "Subscribe to provider events without entity storage", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "event_types": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "minItems": 1, "maxItems": 32 } }, "required": [ "connection_id", "event_types" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Configured event subscription", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "source_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connector_id": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "enabled_at": { "type": "string", "format": "date-time" }, "payload_retention_seconds": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "id", "connection_id", "source_id", "connector_id", "event_types", "status", "version", "enabled_at", "payload_retention_seconds" ], "additionalProperties": false } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "get": { "operationId": "getProviderEventSubscription", "summary": "Read the connection event subscription", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "connection_id", "in": "query" } ], "responses": { "200": { "description": "Subscription or null", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "source_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connector_id": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "enabled_at": { "type": "string", "format": "date-time" }, "payload_retention_seconds": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "id", "connection_id", "source_id", "connector_id", "event_types", "status", "version", "enabled_at", "payload_retention_seconds" ], "additionalProperties": false } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/provider-event-subscriptions/{subscriptionId}": { "delete": { "operationId": "disableProviderEventSubscription", "summary": "Disable a provider event subscription", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "required": true, "name": "subscriptionId", "in": "path" } ], "responses": { "200": { "description": "Disabled subscription", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connection_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "source_id": { "type": "string", "format": "uuid", "example": "9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f" }, "connector_id": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0 }, "enabled_at": { "type": "string", "format": "date-time" }, "payload_retention_seconds": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "id", "connection_id", "source_id", "connector_id", "event_types", "status", "version", "enabled_at", "payload_retention_seconds" ], "additionalProperties": false } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connectors/{connectorId}/endpoints": { "get": { "operationId": "listConnectorEndpoints", "summary": "List a connector's raw API endpoints", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": true, "name": "connectorId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": false, "name": "group", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "`true` lists the endpoints a lock regeneration removed (with `removed_at`) beside the live ones" }, "required": false, "description": "`true` lists the endpoints a lock regeneration removed (with `removed_at`) beside the live ones", "name": "include_removed", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^[A-Za-z0-9_-]+$", "description": "Opaque pagination cursor from a previous response" }, "required": false, "description": "Opaque pagination cursor from a previous response", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size (1-100, default 20)" }, "required": false, "description": "Page size (1-100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Endpoints ordered by id, without schemas, each with its descriptor; `q` matches id, path or summary, `group` narrows to one vendor group, `include_removed=true` lists tombstoned endpoints too", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointListResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connectors/{connectorId}/endpoint": { "get": { "operationId": "getConnectorEndpoint", "summary": "Get one raw endpoint, by method and vendor path, with its JSON schemas", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": true, "name": "connectorId", "in": "path" }, { "schema": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "required": true, "name": "method", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "^\\/", "example": "/api/v4/leads/{id}" }, "required": true, "name": "path", "in": "query" } ], "responses": { "200": { "description": "Endpoint detail with input and output schemas and its paging descriptor", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointDetail" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found). No such endpoint — or a lock regeneration removed it, in which case the problem detail names when, and its last descriptor digest when one was recorded (`include_removed=true` on the list still shows it)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/connectors/{connectorId}/openapi.json": { "get": { "operationId": "getConnectorOpenApi", "summary": "The connector's mirror call surface as one OpenAPI 3.1 document", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": true, "name": "connectorId", "in": "path" } ], "responses": { "200": { "description": "OpenAPI 3.1: every live catalogued endpoint as an operation on `/v1/api/{connectorId}` + the vendor path, with the bearer security scheme and the `Context4-Connection-Id` header on each; deterministic for an unchanged catalogue, and `ETag` carries the document's sha256", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorOpenApiDocument" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found). No connector of that id has catalogued endpoints", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/endpoints/search": { "post": { "operationId": "searchEndpoints", "summary": "Search raw endpoints across the connectors the caller has a usable connection for", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointSearchRequest" } } } }, "responses": { "200": { "description": "Hits ranked by relevance within the scope — the connectors of the workspace's active connections (or of the connections the named `borrowers` lend), narrowed by `connectors`; an empty scope answers no items and no error. `scope.index` names the index that answered (`ratel`, or `ilike` while the registry is unbuilt or disabled)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointSearchResponse" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/api/{connectorId}/{vendorPath}": { "get": { "operationId": "callConnectorApiGet", "summary": "GET a catalogued vendor endpoint through a connection (mirror path)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": true, "name": "connectorId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The vendor path after `/v1/api/{connectorId}/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter", "example": "api/v4/leads/7" }, "required": true, "description": "The vendor path after `/v1/api/{connectorId}/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter", "name": "vendorPath", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)", "example": "3f1c2a9e-8b4d-4c55-9a0e-6d2f1b7c8e90" }, "required": true, "description": "The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)", "name": "Context4-Connection-Id", "in": "header" } ], "responses": { "200": { "description": "The vendor's response, status and body unchanged, with `Context4-Execution-Id` and `Context4-Origin: provider`; a platform refusal is a problem document with `Context4-Origin: platform`", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "callConnectorApiPost", "summary": "POST a catalogued vendor endpoint through a connection (mirror path)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": true, "name": "connectorId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The vendor path after `/v1/api/{connectorId}/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter", "example": "api/v4/leads/7" }, "required": true, "description": "The vendor path after `/v1/api/{connectorId}/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter", "name": "vendorPath", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)", "example": "3f1c2a9e-8b4d-4c55-9a0e-6d2f1b7c8e90" }, "required": true, "description": "The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)", "name": "Context4-Connection-Id", "in": "header" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorApiBody" } } } }, "responses": { "200": { "description": "The vendor's response, status and body unchanged, with `Context4-Execution-Id` and `Context4-Origin: provider`; a platform refusal is a problem document with `Context4-Origin: platform`", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "put": { "operationId": "callConnectorApiPut", "summary": "PUT a catalogued vendor endpoint through a connection (mirror path)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": true, "name": "connectorId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The vendor path after `/v1/api/{connectorId}/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter", "example": "api/v4/leads/7" }, "required": true, "description": "The vendor path after `/v1/api/{connectorId}/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter", "name": "vendorPath", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)", "example": "3f1c2a9e-8b4d-4c55-9a0e-6d2f1b7c8e90" }, "required": true, "description": "The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)", "name": "Context4-Connection-Id", "in": "header" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorApiBody" } } } }, "responses": { "200": { "description": "The vendor's response, status and body unchanged, with `Context4-Execution-Id` and `Context4-Origin: provider`; a platform refusal is a problem document with `Context4-Origin: platform`", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "callConnectorApiPatch", "summary": "PATCH a catalogued vendor endpoint through a connection (mirror path)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": true, "name": "connectorId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The vendor path after `/v1/api/{connectorId}/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter", "example": "api/v4/leads/7" }, "required": true, "description": "The vendor path after `/v1/api/{connectorId}/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter", "name": "vendorPath", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)", "example": "3f1c2a9e-8b4d-4c55-9a0e-6d2f1b7c8e90" }, "required": true, "description": "The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)", "name": "Context4-Connection-Id", "in": "header" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorApiBody" } } } }, "responses": { "200": { "description": "The vendor's response, status and body unchanged, with `Context4-Execution-Id` and `Context4-Origin: provider`; a platform refusal is a problem document with `Context4-Origin: platform`", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "callConnectorApiDelete", "summary": "DELETE a catalogued vendor endpoint through a connection (mirror path)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,78}$", "example": "bitrix24" }, "required": true, "name": "connectorId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The vendor path after `/v1/api/{connectorId}/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter", "example": "api/v4/leads/7" }, "required": true, "description": "The vendor path after `/v1/api/{connectorId}/`, exactly as the vendor documents it. Its slashes may be sent literally (`api/v4/leads/7`) or, as a generated client encodes one path parameter, percent-encoded as one segment (`api%2Fv4%2Fleads%2F7`). A `/` that belongs inside one vendor parameter (a git ref `heads/main`) is `%2F` in the literal form (`git/ref/heads%2Fmain`) and `%252F` in the encoded one; it reaches the vendor as `%2F` inside that segment, and only where the endpoint's template has a parameter", "name": "vendorPath", "in": "path" }, { "schema": { "type": "string", "format": "uuid", "description": "The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)", "example": "3f1c2a9e-8b4d-4c55-9a0e-6d2f1b7c8e90" }, "required": true, "description": "The connection the vendor call runs on; it must belong to `connectorId` (another connector's connection is `409`)", "name": "Context4-Connection-Id", "in": "header" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorApiBody" } } } }, "responses": { "200": { "description": "The vendor's response, status and body unchanged, with `Context4-Execution-Id` and `Context4-Origin: provider`; a platform refusal is a problem document with `Context4-Origin: platform`", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every response", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Per-key request limit for the current window", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets", "schema": { "type": "integer" } } } }, "400": { "description": "Problem (validation_failed)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Problem (capability_missing, forbidden)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (not_found)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Problem (rate_limited)", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Problem (internal)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Problem (service_unavailable)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "webhooks": {} }