{ "openapi": "3.0.3", "info": { "title": "Cyphrex API", "version": "1.0.0", "description": "Public integration surface: POST /v1/check (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": "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. Success is exactly {\"allowed\":true}. A deny is still HTTP 200 with allowed false, reason, and severity.", "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" }, "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 } }, "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": "Sandbox expired or action cap", "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" }, "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" }, "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": "Paid plan action cap", "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" }, "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" }, "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/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 lookup by blockchain SSN", "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 a Solana 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." } } } }