{ "openapi": "3.0.3", "info": { "title": "Cyphrex API", "version": "1.0.0", "description": "Public integration surface: POST /v1/check and the MCP agent routes (API key), and verification routes (no auth). Dashboard JWT routes are not in this document. Official SDK package name is cyphrex on npm and PyPI. There is no public SDK repository." }, "servers": [ { "url": "https://cyphrexapi-production.up.railway.app", "description": "Production API" }, { "url": "https://cyphrex.io/api", "description": "Site proxy (paths still begin with /v1)" } ], "tags": [ { "name": "check", "description": "Runtime enforcement" }, { "name": "mcp", "description": "API key routes used by the Cyphrex MCP server." }, { "name": "verify", "description": "Public verification. No authentication." } ], "security": [], "paths": { "/v1/check": { "post": { "tags": [ "check" ], "operationId": "checkAction", "summary": "Check whether an agent action is allowed", "description": "Call before executing the action. Required body fields are agentId and nested action.type. A top-level actionType is rejected. Send x-cyphrex-key (primary) or Authorization: Bearer . Official SDKs send both. This is not a dashboard session JWT.", "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "description": "Agent UUID", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "action": { "type": "object", "properties": { "type": { "type": "string", "description": "Action type, e.g. http_call, llm_response, data_access, tool_use", "minLength": 1 }, "url": { "type": "string" }, "payload": {}, "metadata": { "type": "object", "additionalProperties": {} }, "dataScope": { "type": "string" }, "estimatedCost": { "type": "number" }, "tool_name": { "type": "string" }, "toolName": { "type": "string" } }, "additionalProperties": true, "description": "Nested action. Do not send a top-level actionType field.", "required": [ "type" ] } }, "additionalProperties": false, "required": [ "agentId", "action" ] } } } }, "responses": { "200": { "description": "Policy decision. An in-policy success is exactly {\"allowed\":true}. A policy deny is still HTTP 200 with allowed false, reason, and severity. An expired free trial is HTTP 200 with allowed true, enforcement \"off\", and reason \"trial_expired\": the action is recorded and nothing is blocked. Past the 100,000 recorded-action cap the event is still stored. A trial account is shown a count frozen at that cap until the account is paid.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "allowed": { "type": "boolean", "enum": [ true ] } }, "additionalProperties": false, "required": [ "allowed" ] }, { "type": "object", "properties": { "allowed": { "type": "boolean", "enum": [ false ] }, "reason": { "type": "string" }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": true, "required": [ "allowed", "reason", "severity" ] }, { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "off" ] }, "recorded": { "type": "boolean" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "rule": { "type": "string" }, "category": { "type": "string" }, "pii_kind": { "type": "string" }, "matched_topic": { "type": "string" }, "length": { "type": "number" } }, "additionalProperties": false } ] }, "examples": { "allowed": { "value": { "allowed": true } }, "trialExpired": { "value": { "allowed": true, "enforcement": "off", "reason": "trial_expired", "code": "trial_expired" } }, "denied": { "value": { "allowed": false, "reason": "URL not in allowed list", "severity": "P2" } } } } } }, "400": { "description": "Missing agentId or action.type, or agentId is not a UUID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "402": { "description": "While the free trial is active, the enforced-action cap is 25,000. The 100,000 recorded-action cap does not stop storage and is not a 402. After the trial expires, checks stay HTTP 200 and events are still stored. The count shown to a trial account freezes at 100,000 recorded actions until the account is paid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "off" ] }, "recorded": { "type": "boolean" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "rule": { "type": "string" }, "category": { "type": "string" }, "pii_kind": { "type": "string" }, "matched_topic": { "type": "string" }, "length": { "type": "number" } }, "additionalProperties": false } } } }, "403": { "description": "Agent frozen", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "off" ] }, "recorded": { "type": "boolean" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "rule": { "type": "string" }, "category": { "type": "string" }, "pii_kind": { "type": "string" }, "matched_topic": { "type": "string" }, "length": { "type": "number" } }, "additionalProperties": false } } } }, "404": { "description": "Agent not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "429": { "description": "Request rate limit. Paid usage is not blocked for volume.", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "off" ] }, "recorded": { "type": "boolean" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "rule": { "type": "string" }, "category": { "type": "string" }, "pii_kind": { "type": "string" }, "matched_topic": { "type": "string" }, "length": { "type": "number" } }, "additionalProperties": false } } } }, "503": { "description": "Auth lookup, event write, or deadline failure (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "off" ] }, "recorded": { "type": "boolean" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "rule": { "type": "string" }, "category": { "type": "string" }, "pii_kind": { "type": "string" }, "matched_topic": { "type": "string" }, "length": { "type": "number" } }, "additionalProperties": false } } } } } } }, "/v1/mcp/agents": { "post": { "tags": [ "mcp" ], "operationId": "registerMcpAgent", "summary": "Register an agent", "description": "API key auth, same as POST /v1/check: x-cyphrex-key or Authorization: Bearer. Creates an active agent and an empty behavior profile. description is stored as purpose. Returns 402 when the account is already at its active-agent limit.", "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Agent name", "minLength": 1 }, "type": { "type": "string", "description": "Stored as agents.type" }, "description": { "type": "string", "description": "Stored as agents.purpose" } }, "additionalProperties": true, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created agent row", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "nullable": true }, "purpose": { "type": "string", "nullable": true }, "version": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true }, "trust_score": { "type": "number" }, "trust_tier": { "type": "number" }, "trust_score_updated_at": { "type": "string", "nullable": true }, "store_payloads": { "type": "boolean" }, "enforcement_mode": { "type": "string" }, "anchor_lease_until": { "type": "string", "nullable": true }, "last_anchored_at": { "type": "string", "nullable": true }, "last_anchor_id": { "type": "string", "nullable": true } }, "additionalProperties": true, "required": [ "id", "account_id", "name" ] } }, "additionalProperties": false, "required": [ "agent" ] } } } }, "400": { "description": "name is required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "402": { "description": "Active agent count is at the plan limit. error is the paid-plan message and code is paid_plan_required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "error", "code" ] } } } }, "500": { "description": "Could not count agents, insert the agent, or create the behavior profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "503": { "description": "API key lookup failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "error", "code" ] } } } } } } }, "/v1/mcp/agents/{id}/check": { "post": { "tags": [ "mcp" ], "operationId": "checkMcpAgentAction", "summary": "Check whether an agent action is allowed", "description": "Same policy handler as POST /v1/check. The agent id is the path parameter, not a body field. A string action is normalized to type tool_use with that string as payload before the check. An object action must include type. Send x-cyphrex-key or Authorization: Bearer. This is not a dashboard session JWT.", "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent UUID", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "description": "Shorthand. Becomes type tool_use with this string as payload.", "minLength": 1 }, { "type": "object", "properties": { "type": { "type": "string", "description": "Action type, e.g. http_call, llm_response, data_access, tool_use", "minLength": 1 }, "url": { "type": "string" }, "payload": {}, "metadata": { "type": "object", "additionalProperties": {} }, "dataScope": { "type": "string" }, "estimatedCost": { "type": "number" }, "tool_name": { "type": "string" }, "toolName": { "type": "string" } }, "additionalProperties": true, "description": "Nested action. Do not send a top-level actionType field.", "required": [ "type" ] } ] } }, "additionalProperties": true, "required": [ "action" ] } } } }, "responses": { "200": { "description": "Policy decision. An in-policy success is exactly {\"allowed\":true}. A policy deny is still HTTP 200 with allowed false, reason, and severity. An expired free trial is HTTP 200 with allowed true, enforcement \"off\", and reason \"trial_expired\": the action is recorded and nothing is blocked. Past the 100,000 recorded-action cap the event is still stored. A trial account is shown a count frozen at that cap until the account is paid.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "allowed": { "type": "boolean", "enum": [ true ] } }, "additionalProperties": false, "required": [ "allowed" ] }, { "type": "object", "properties": { "allowed": { "type": "boolean", "enum": [ false ] }, "reason": { "type": "string" }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" } }, "additionalProperties": true, "required": [ "allowed", "reason", "severity" ] }, { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "off" ] }, "recorded": { "type": "boolean" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "rule": { "type": "string" }, "category": { "type": "string" }, "pii_kind": { "type": "string" }, "matched_topic": { "type": "string" }, "length": { "type": "number" } }, "additionalProperties": false } ] }, "examples": { "allowed": { "value": { "allowed": true } }, "trialExpired": { "value": { "allowed": true, "enforcement": "off", "reason": "trial_expired", "code": "trial_expired" } }, "denied": { "value": { "allowed": false, "reason": "URL not in allowed list", "severity": "P2" } } } } } }, "400": { "description": "Missing action.type, or the agent id is not a UUID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "402": { "description": "While the free trial is active, the enforced-action cap is 25,000. The 100,000 recorded-action cap does not stop storage and is not a 402. After the trial expires, checks stay HTTP 200 and events are still stored. The count shown to a trial account freezes at 100,000 recorded actions until the account is paid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "off" ] }, "recorded": { "type": "boolean" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "rule": { "type": "string" }, "category": { "type": "string" }, "pii_kind": { "type": "string" }, "matched_topic": { "type": "string" }, "length": { "type": "number" } }, "additionalProperties": false } } } }, "403": { "description": "Agent frozen", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "off" ] }, "recorded": { "type": "boolean" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "rule": { "type": "string" }, "category": { "type": "string" }, "pii_kind": { "type": "string" }, "matched_topic": { "type": "string" }, "length": { "type": "number" } }, "additionalProperties": false } } } }, "404": { "description": "Agent not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "429": { "description": "Request rate limit. Paid usage is not blocked for volume.", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "off" ] }, "recorded": { "type": "boolean" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "rule": { "type": "string" }, "category": { "type": "string" }, "pii_kind": { "type": "string" }, "matched_topic": { "type": "string" }, "length": { "type": "number" } }, "additionalProperties": false } } } }, "503": { "description": "Auth lookup, event write, or deadline failure (fail-closed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "severity": { "type": "string" }, "violation_type": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "off" ] }, "recorded": { "type": "boolean" }, "message": { "type": "string" }, "upgrade_url": { "type": "string" }, "rule": { "type": "string" }, "category": { "type": "string" }, "pii_kind": { "type": "string" }, "matched_topic": { "type": "string" }, "length": { "type": "number" } }, "additionalProperties": false } } } } } } }, "/v1/mcp/agents/{id}/audit-log": { "get": { "tags": [ "mcp" ], "operationId": "getMcpAgentAuditLog", "summary": "Audit log for one agent", "description": "API key auth, same as POST /v1/check. Returns events for that agent, newest first. An unknown or inactive agent is HTTP 403, not 404. limit defaults to 50 and is clamped to 1..500.", "security": [ { "ApiKeyHeader": [] }, { "ApiKeyBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many events to return. Omitted or not a number uses 50. Below 1 becomes 1. Above 500 becomes 500.", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Newest events for the agent", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agent_id": { "type": "string", "nullable": true }, "account_id": { "type": "string", "nullable": true }, "action_type": { "type": "string" }, "allowed": { "type": "boolean" }, "severity": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "data_scope": { "type": "string", "nullable": true }, "payload": { "type": "string", "nullable": true }, "kind": { "type": "string", "nullable": true }, "control_ids": { "type": "array", "items": { "type": "string" } }, "framework_tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "nullable": true } }, "additionalProperties": true, "required": [ "id", "action_type", "allowed" ] } } }, "additionalProperties": false, "required": [ "events" ] } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "403": { "description": "Agent not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "500": { "description": "Could not read events", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "503": { "description": "API key lookup failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false, "required": [ "error", "code" ] } } } } } } }, "/v1/keys": { "get": { "tags": [ "verify" ], "operationId": "listSigningKeys", "summary": "Published signing-key registry", "security": [], "responses": { "200": { "description": "Active and published signing keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "validFrom": { "type": "string", "nullable": true }, "validTo": { "type": "string", "nullable": true }, "status": { "type": "string" } }, "additionalProperties": true, "required": [ "id" ] } }, "activeKeyId": { "type": "string" } }, "additionalProperties": false, "required": [ "keys", "activeKeyId" ] } } } }, "500": { "description": "Lookup failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } } } } }, "/v1/keys/{keyId}": { "get": { "tags": [ "verify" ], "operationId": "getSigningKeyPem", "summary": "Ed25519 public key PEM", "description": "Returns text/plain PEM. The HTML page at /keys/:keyId is documentation, not the key.", "security": [], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "example": "cyphrex-signer-prod-01" } } ], "responses": { "200": { "description": "PEM", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid key id", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Key not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } } } } }, "/v1/verify/{ssn}": { "get": { "tags": [ "verify" ], "operationId": "verifyBlockchainSsn", "summary": "Public agent identity lookup", "security": [], "parameters": [ { "name": "ssn", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verified agent metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "enum": [ true ] }, "agent_type": { "type": "string", "nullable": true }, "registered_at": { "type": "string", "nullable": true }, "created_at": { "type": "string", "nullable": true }, "action_count": { "type": "number" }, "status": { "type": "string" }, "owner_wallet": { "type": "string", "nullable": true } }, "additionalProperties": false, "required": [ "verified", "action_count" ] } } } }, "400": { "description": "Invalid SSN", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Unknown SSN", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "500": { "description": "Verification failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } } } } }, "/v1/inclusion/verify": { "post": { "tags": [ "verify" ], "operationId": "verifyInclusion", "summary": "Public Merkle inclusion check", "description": "Body is a whole package ({ package } or { report }) or a single { event, proof }. Membership of a closed leaf, not completeness.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "object", "additionalProperties": {} }, "report": { "type": "object", "additionalProperties": {} }, "event": { "type": "object", "additionalProperties": {} }, "proof": { "type": "object", "additionalProperties": {} } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Inclusion result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "signature": { "type": "object", "additionalProperties": {} }, "events": { "type": "array", "items": { "type": "object", "properties": { "ok": { "type": "boolean" }, "anchored": { "type": "boolean" }, "rootMatches": { "type": "boolean" }, "merkleRoot": { "type": "string", "nullable": true }, "txSignature": { "type": "string", "nullable": true }, "network": { "type": "string", "nullable": true }, "leafIndex": { "type": "number" }, "treeSize": { "type": "number" }, "detail": { "type": "string" }, "eventId": {}, "chain": { "type": "object", "properties": { "checked": { "type": "boolean" }, "onChain": { "type": "boolean" }, "detail": { "type": "string" }, "block_height": { "type": "number", "nullable": true }, "slot": { "type": "number", "nullable": true }, "confirmations": { "type": "number", "nullable": true } }, "additionalProperties": true } }, "additionalProperties": true } }, "anchoredCount": { "type": "number" }, "unanchoredCount": { "type": "number" }, "event": { "type": "object", "properties": { "ok": { "type": "boolean" }, "anchored": { "type": "boolean" }, "rootMatches": { "type": "boolean" }, "merkleRoot": { "type": "string", "nullable": true }, "txSignature": { "type": "string", "nullable": true }, "network": { "type": "string", "nullable": true }, "leafIndex": { "type": "number" }, "treeSize": { "type": "number" }, "detail": { "type": "string" }, "eventId": {}, "chain": { "type": "object", "properties": { "checked": { "type": "boolean" }, "onChain": { "type": "boolean" }, "detail": { "type": "string" }, "block_height": { "type": "number", "nullable": true }, "slot": { "type": "number", "nullable": true }, "confirmations": { "type": "number", "nullable": true } }, "additionalProperties": true } }, "additionalProperties": true }, "chain": { "type": "object", "properties": { "checked": { "type": "boolean" }, "onChain": { "type": "boolean" }, "detail": { "type": "string" }, "block_height": { "type": "number", "nullable": true }, "slot": { "type": "number", "nullable": true }, "confirmations": { "type": "number", "nullable": true } }, "additionalProperties": true }, "error": { "type": "string" }, "detail": { "type": "string" }, "sha256": { "type": "string" }, "canonical": { "type": "string" } }, "additionalProperties": true, "required": [ "ok" ] } } } }, "400": { "description": "Missing package or event/proof", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } } } } }, "/v1/reports/{id}/public": { "get": { "tags": [ "verify" ], "operationId": "getPublicReport", "summary": "Opted-in signed report JSON", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Signed package", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {}, "description": "Signed evidence package JSON when public=true" } } } }, "400": { "description": "Invalid report id", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found or not public", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } } } } }, "/v1/reports/by-pdf-sha256/{sha256}": { "get": { "tags": [ "verify" ], "operationId": "getReportByPdfSha256", "summary": "Signed JSON bound to a PDF SHA-256", "security": [], "parameters": [ { "name": "sha256", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "responses": { "200": { "description": "Signed package", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {}, "description": "Signed evidence package JSON when public=true" } } } }, "400": { "description": "Invalid PDF SHA-256", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error" ] } } } } } } }, "/v1/solana/verify": { "post": { "tags": [ "verify" ], "operationId": "verifySolanaAnchor", "summary": "Confirm an anchor transaction references a report hash", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "anchor_tx_signature": { "type": "string" }, "sha256": { "type": "string" }, "signature": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Anchor check", "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmed": { "type": "boolean" }, "detail": { "type": "string" }, "block_height": { "type": "number", "nullable": true }, "slot": { "type": "number", "nullable": true }, "confirmations": { "type": "number", "nullable": true }, "error": { "type": "string" } }, "additionalProperties": true, "required": [ "confirmed" ] } } } }, "500": { "description": "Verification failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmed": { "type": "boolean" }, "detail": { "type": "string" }, "block_height": { "type": "number", "nullable": true }, "slot": { "type": "number", "nullable": true }, "confirmations": { "type": "number", "nullable": true }, "error": { "type": "string" } }, "additionalProperties": true, "required": [ "confirmed" ] } } } } } } } }, "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-cyphrex-key", "description": "Primary API key header. Keys start with cprx_live_." }, "ApiKeyBearer": { "type": "http", "scheme": "bearer", "description": "Same API key as x-cyphrex-key, as Authorization: Bearer cprx_live_.... Not a dashboard session JWT." } } } }