openapi: 3.0.3 info: title: Truthlocks API description: 'Truthlocks is a universal verification infrastructure for documents, credentials, and digital assets. This specification defines the canonical API for interacting with Truthlocks services. ## Base URLs - **Production**: `https://api.truthlocks.com` - **Sandbox**: `https://sandbox-api.truthlocks.com` ## Authentication - **API Keys**: Use `X-API-Key` header for machine-to-machine operations - **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated operations ## Tenant Identity In production, tenant identity is derived from the authenticated context (API key or JWT). The `X-Tenant-ID` header is ignored in production to prevent spoofing. ' version: 1.0.0 contact: name: Truthlocks Support url: https://truthlocks.com/support email: support@truthlocks.com externalDocs: description: Transparency read-only API (separate service spec) url: https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml servers: - url: https://api.truthlocks.com description: Production API - url: https://sandbox-api.truthlocks.com description: Sandbox Environment tags: - name: Authentication description: API key and token management - name: Issuers description: Issuer registration and trust management - name: Keys description: Cryptographic key management for issuers - name: Attestations description: Attestation lifecycle (mint, revoke, supersede) - name: Verification description: Attestation verification and proof bundles - name: Governance description: Issuer governance workflows (admin only) - name: Identity description: Organization, user, and role management - name: Audit description: Audit event queries - name: Platform description: Platform administration (super admin only) - name: Platform Review description: Staff review workflows for issuer applications - name: Tenant Console description: Tenant profile and lifecycle endpoints - name: Health description: Service health and readiness endpoints - name: Risk description: Risk signal ingestion and fraud detection - name: Risk Enforcement description: Risk enforcement actions — block, challenge, quarantine, and configuration - name: Billing description: Billing, subscription, and addon management - name: Machine Identity description: Machine Agent Identity Protocol (MAIP) — agent registration, sessions, trust, witness, compliance, orchestration, and observability components: securitySchemes: APIKey: type: apiKey in: header name: X-API-Key description: API key for machine-to-machine authentication BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT for user-initiated operations schemas: ErrorEnvelope: type: object required: - code - message - http_status properties: code: type: string description: Machine-readable error code enum: - AUTH_REQUIRED - AUTH_INVALID - PERMISSION_DENIED - TENANT_IDENTITY_UNVERIFIED - NOT_FOUND - VALIDATION_ERROR - CONFLICT - PAYLOAD_TOO_LARGE - RATE_LIMIT_EXCEEDED - QUOTA_EXCEEDED - SERVICE_UNAVAILABLE - INTERNAL_ERROR message: type: string description: Human-readable error message http_status: type: integer description: HTTP status code retry_after_ms: type: integer description: Milliseconds to wait before retrying (for rate limits) details: type: object description: Additional error context example: code: AUTH_REQUIRED message: Authentication required http_status: 401 Issuer: type: object properties: id: type: string format: uuid tenant_id: type: string format: uuid name: type: string domain: type: string status: type: string enum: - PENDING - APPROVED - SUSPENDED - REVOKED trust_level: type: string enum: - BASIC - VERIFIED - ENTERPRISE created_at: type: string format: date-time updated_at: type: string format: date-time SigningAlgorithm: type: string enum: - Ed25519 - ES256 - ES384 - ES512 - RS256 - RS384 - RS512 - PS256 - PS384 - PS512 description: Signing algorithm for key generation Key: type: object properties: kid: type: string description: Key identifier issuer_id: type: string format: uuid algorithm: $ref: '#/components/schemas/SigningAlgorithm' public_key: type: string description: Base64-encoded public key status: type: string enum: - ACTIVE - DISABLED - EXPIRED not_before: type: string format: date-time expires_at: type: string format: date-time Attestation: type: object properties: id: type: string format: uuid issuer_id: type: string format: uuid kid: type: string status: type: string enum: - VALID - REVOKED - SUPERSEDED payload: type: object signature: type: string log_index: type: integer created_at: type: string format: date-time ProofBundle: type: object properties: attestation: $ref: '#/components/schemas/Attestation' issuer: $ref: '#/components/schemas/Issuer' key: $ref: '#/components/schemas/Key' inclusion_proof: type: object properties: log_index: type: integer root_hash: type: string hashes: type: array items: type: string signed_tree_head: type: object properties: tree_size: type: integer root_hash: type: string signature: type: string VerifyRequest: type: object required: - attestation_id properties: attestation_id: type: string format: uuid description: The unique identifier of the attestation to verify. payload_b64url: type: string description: 'Base64url-encoded payload for signature verification. If provided, the system verifies that the SHA-256 hash of this payload matches the stored payload_hash. Use this to confirm you hold the exact original content that was attested. ' document_hash_hex: type: string description: 'SHA-256 hex hash of the original document for integrity verification. If provided, compared against the stored document_hash. Use this when you want to verify a file''s integrity without sending the full payload over the wire. ' VerifyResponse: type: object properties: verdict: $ref: '#/components/schemas/Verdict' valid: type: boolean details: type: object properties: issuer_id: type: string format: uuid issuer_name: type: string log_index: type: integer checked_at: type: string format: date-time Verdict: type: string enum: - VALID - INVALID - REVOKED - ALTERED - SUPERSEDED - UNKNOWN description: '- **VALID**: Signature verified and attestation is active - **REVOKED**: Attestation was explicitly revoked - **SUPERSEDED**: Attestation replaced by a newer version - **ALTERED**: Signature verification failed (tampered) - **INVALID**: General validation failure - **UNKNOWN**: Attestation not found ' Organization: type: object properties: id: type: string format: uuid tenant_id: type: string format: uuid name: type: string slug: type: string status: type: string enum: - ACTIVE - SUSPENDED created_at: type: string format: date-time User: type: object properties: id: type: string format: uuid org_id: type: string format: uuid email: type: string format: email name: type: string status: type: string enum: - ACTIVE - INVITED - SUSPENDED created_at: type: string format: date-time Role: type: object properties: id: type: string format: uuid name: type: string permissions: type: array items: type: string APIKey: type: object properties: id: type: string format: uuid name: type: string prefix: type: string description: First 8 characters of the key status: type: string enum: - ACTIVE - REVOKED scopes: type: array items: type: string daily_quota: type: integer rate_limit_per_minute: type: integer created_at: type: string format: date-time ConsumerAPIKey: type: object properties: key_id: type: string format: uuid name: type: string description: Human-readable label for the key prefix: type: string description: First 12 characters of the key, for display purposes status: type: string enum: - active - revoked scopes: type: array items: type: string description: Permission scopes granted to this key created_at: type: string format: date-time expires_at: type: string format: date-time description: Keys expire 90 days after creation last_used_at: type: string format: date-time description: Timestamp of the last request made with this key AuditEvent: type: object properties: id: type: string format: uuid tenant_id: type: string format: uuid actor_id: type: string actor_type: type: string enum: - USER - API_KEY - SYSTEM action: type: string resource_type: type: string resource_id: type: string metadata: type: object timestamp: type: string format: date-time Tenant: type: object properties: id: type: string format: uuid name: type: string slug: type: string status: type: string enum: - PENDING - ONBOARDING - ACTIVE - SUSPENDED tier: type: string enum: - FREE - STARTER - PROFESSIONAL - ENTERPRISE created_at: type: string format: date-time RiskSignal: type: object properties: id: type: string format: uuid tenant_id: type: string format: uuid source: type: string description: Origin of the signal (e.g. device_fingerprint, ip_reputation, email_verification, document_analysis, behavioral) example: device_fingerprint signal_type: type: string description: Classification of the risk signal example: velocity_anomaly score: type: number format: float minimum: 0 maximum: 1 description: Risk score between 0 (no risk) and 1 (highest risk) example: 0.85 details: type: object additionalProperties: true description: Arbitrary metadata associated with the signal example: ip: 203.0.113.42 country: US reason: multiple_accounts_same_device entity_type: type: string description: The type of entity this signal relates to enum: - user - device - ip - document - session example: user entity_id: type: string description: Identifier of the entity being evaluated example: usr_8f14e45f created_at: type: string format: date-time MaipAgent: type: object properties: id: type: string format: uuid agent_type: type: string enum: - orchestrator - worker - inference - pipeline - service - bot - llm display_name: type: string maxLength: 256 description: type: string status: type: string enum: - active - suspended - revoked scopes: type: array items: type: string metadata: type: object additionalProperties: true trust_score: type: number format: float minimum: 0 maximum: 1 public_key: type: string description: Base64-encoded public key session_count: type: integer keys: type: array items: type: object properties: kid: type: string algorithm: type: string public_key: type: string status: type: string enum: - active - disabled - expired created_at: type: string format: date-time updated_at: type: string format: date-time MaipAgentList: type: object properties: items: type: array items: $ref: '#/components/schemas/MaipAgent' total: type: integer MaipSession: type: object properties: session_id: type: string format: uuid agent_id: type: string format: uuid token: type: string description: Session bearer token (returned once on creation) scopes: type: array items: type: string status: type: string enum: - active - terminated - expired metadata: type: object additionalProperties: true expires_at: type: string format: date-time created_at: type: string format: date-time terminated_at: type: string format: date-time MaipSessionList: type: object properties: items: type: array items: $ref: '#/components/schemas/MaipSession' total: type: integer MaipTool: type: object properties: tool_id: type: string format: uuid name: type: string description: type: string schema: type: object additionalProperties: true agent_id: type: string format: uuid created_at: type: string format: date-time MaipToolInvocationResult: type: object properties: result: type: object additionalProperties: true receipt_id: type: string format: uuid execution_ms: type: integer MaipTrustScore: type: object properties: score: type: number format: float minimum: 0 maximum: 1 factors: type: object additionalProperties: true deltas: type: object additionalProperties: true computed_at: type: string format: date-time MaipTrustHistory: type: object properties: history: type: array items: type: object properties: score: type: number format: float minimum: 0 maximum: 1 timestamp: type: string format: date-time factors: type: object additionalProperties: true MaipWitnessGroup: type: object properties: witness_id: type: string format: uuid name: type: string required_attestations: type: integer agent_ids: type: array items: type: string format: uuid status: type: string enum: - pending - active - completed created_at: type: string format: date-time MaipAttestation: type: object properties: attestation_id: type: string format: uuid witness_id: type: string format: uuid agent_id: type: string format: uuid claim_hash: type: string signature: type: string status: type: string enum: - pending - accepted - rejected created_at: type: string format: date-time MaipConsensus: type: object properties: reached: type: boolean attestation_count: type: integer required: type: integer signatures: type: array items: type: string MaipTruthClaim: type: object properties: claim_id: type: string format: uuid agent_id: type: string format: uuid claim_type: type: string payload: type: object additionalProperties: true evidence: type: array items: type: object additionalProperties: true status: type: string enum: - pending - verified - rejected - expired receipt_id: type: string format: uuid attestations: type: array items: $ref: '#/components/schemas/MaipAttestation' verified_at: type: string format: date-time created_at: type: string format: date-time MaipTruthVerification: type: object properties: valid: type: boolean verification_result: type: object additionalProperties: true receipt: type: object additionalProperties: true MaipDocumentVerification: type: object properties: verification_id: type: string format: uuid document_id: type: string format: uuid document_hash: type: string status: type: string enum: - pending - verified - failed results: type: array items: type: object additionalProperties: true verifications: type: array items: type: object additionalProperties: true claims: type: array items: $ref: '#/components/schemas/MaipTruthClaim' created_at: type: string format: date-time MaipComplianceCheck: type: object properties: check_id: type: string format: uuid agent_id: type: string format: uuid framework: type: string enum: - soc2 - iso27001 - hipaa - gdpr scope: type: object additionalProperties: true status: type: string enum: - pending - passed - failed - partial findings: type: array items: type: object properties: finding_id: type: string severity: type: string enum: - low - medium - high - critical title: type: string description: type: string created_at: type: string format: date-time MaipComplianceReportList: type: object properties: items: type: array items: $ref: '#/components/schemas/MaipComplianceCheck' total: type: integer MaipAnomaly: type: object properties: anomaly_id: type: string format: uuid agent_id: type: string format: uuid anomaly_type: type: string severity: type: string enum: - low - medium - high - critical details: type: object additionalProperties: true status: type: string enum: - open - investigating - resolved - dismissed resolution: type: string resolved_by: type: string created_at: type: string format: date-time resolved_at: type: string format: date-time MaipDataset: type: object properties: dataset_id: type: string format: uuid receipt_id: type: string format: uuid name: type: string hash: type: string format: type: string size_bytes: type: integer format: int64 agent_id: type: string format: uuid metadata: type: object additionalProperties: true created_at: type: string format: date-time MaipDatasetList: type: object properties: items: type: array items: $ref: '#/components/schemas/MaipDataset' total: type: integer MaipDatasetLineage: type: object properties: dataset_id: type: string format: uuid lineage: type: array items: type: object properties: transformation: type: string source_dataset_id: type: string format: uuid agent_id: type: string format: uuid timestamp: type: string format: date-time MaipModel: type: object properties: model_id: type: string format: uuid receipt_id: type: string format: uuid name: type: string hash: type: string framework: type: string version: type: string agent_id: type: string format: uuid training_dataset_ids: type: array items: type: string format: uuid created_at: type: string format: date-time MaipModelLineage: type: object properties: model_id: type: string format: uuid training_runs: type: array items: type: object additionalProperties: true datasets: type: array items: $ref: '#/components/schemas/MaipDataset' parent_models: type: array items: $ref: '#/components/schemas/MaipModel' MaipOrchestration: type: object properties: orchestration_id: type: string format: uuid workflow_id: type: string format: uuid agents: type: array items: type: string format: uuid parameters: type: object additionalProperties: true status: type: string enum: - pending - running - completed - failed - cancelled steps: type: array items: type: object properties: step_id: type: string agent_id: type: string format: uuid action: type: string status: type: string result: type: object additionalProperties: true started_at: type: string format: date-time completed_at: type: string format: date-time results: type: object additionalProperties: true receipts: type: array items: type: string format: uuid created_at: type: string format: date-time MaipLlmInferenceResult: type: object properties: response: type: string receipt_id: type: string format: uuid tokens_used: type: integer cost: type: number format: float MaipWorkflow: type: object properties: workflow_id: type: string format: uuid name: type: string steps: type: array items: type: object properties: action: type: string agent_id: type: string format: uuid parameters: type: object additionalProperties: true triggers: type: object additionalProperties: true created_at: type: string format: date-time MaipWorkflowExecution: type: object properties: execution_id: type: string format: uuid workflow_id: type: string format: uuid status: type: string enum: - pending - running - completed - failed steps: type: array items: type: object properties: action: type: string agent_id: type: string format: uuid status: type: string result: type: object additionalProperties: true created_at: type: string format: date-time MaipGuardrailResult: type: object properties: allowed: type: boolean violations: type: array items: type: object properties: rule: type: string description: type: string severity: type: string enum: - low - medium - high - critical receipt_id: type: string format: uuid MaipDelegation: type: object properties: delegation_id: type: string format: uuid from_agent_id: type: string format: uuid to_agent_id: type: string format: uuid scopes: type: array items: type: string ttl_seconds: type: integer conditions: type: object additionalProperties: true status: type: string enum: - offered - active - expired - revoked token: type: string description: Delegation acceptance token (returned on offer) created_at: type: string format: date-time expires_at: type: string format: date-time MaipObservabilityEvent: type: object properties: event_id: type: string format: uuid agent_id: type: string format: uuid event_type: type: string payload: type: object additionalProperties: true timestamp: type: string format: date-time MaipObservabilityEventList: type: object properties: items: type: array items: $ref: '#/components/schemas/MaipObservabilityEvent' total: type: integer MaipPolicy: type: object properties: id: type: string format: uuid description: UUID primary key tenant_id: type: string format: uuid description: UUID of the owning tenant name: type: string description: Human-readable policy name description: type: string description: Detailed policy description category: type: string enum: - scope - trust - rate - custom description: Policy category status: type: string enum: - active - disabled - archived description: Policy lifecycle status priority: type: integer description: Evaluation priority (lower = first) rules: type: array items: $ref: '#/components/schemas/MaipPolicyRule' description: Array of policy rules created_at: type: string format: date-time updated_at: type: string format: date-time MaipPolicyRule: type: object properties: conditions: type: array items: $ref: '#/components/schemas/MaipPolicyCondition' description: Conditions that must all match (AND logic) effect: type: string enum: - allow - deny - require_approval description: Action to take when conditions match requires_approval: type: boolean description: Whether human approval is required MaipPolicyCondition: type: object properties: field: type: string enum: - trust_score - scope - agent_type - delegation_depth description: The field to evaluate op: type: string enum: - eq - ne - lt - gt - le - ge - in - contains description: Comparison operator value: description: Value to compare against (type depends on field) MaipPolicyEvaluateResponse: type: object properties: allowed: type: boolean description: Whether the action is permitted denied_by: type: array items: type: string description: Names of policies that denied the action reason: type: string description: Human-readable denial reason requires_approval: type: boolean description: Whether human approval is required MaipMetrics: type: object properties: metrics: type: array items: type: object properties: name: type: string values: type: array items: type: object properties: timestamp: type: string format: date-time value: type: number format: float paths: /v1/api-keys: get: summary: List API Keys description: Returns all API keys for the authenticated organization. Secrets are masked. tags: - Authentication security: - APIKey: [] - BearerAuth: [] responses: '200': description: List of API keys content: application/json: schema: type: array items: $ref: '#/components/schemas/APIKey' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: AUTH_REQUIRED message: Authentication required http_status: 401 post: summary: Create API Key description: Creates a new API key. The secret is returned once and cannot be retrieved again. tags: - Authentication security: - APIKey: [] - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: Human-readable name for the key scopes: type: array items: type: string description: Permission scopes (default is wildcard) example: name: Production API Key scopes: - attestations:mint - attestations:read responses: '201': description: API key created content: application/json: schema: type: object properties: id: type: string format: uuid name: type: string secret: type: string description: Full API key (shown once) example: id: 550e8400-e29b-41d4-a716-446655440000 name: Production API Key secret: tl_live_abc123xyz789... /v1/api-keys/{id}: delete: summary: Revoke API Key description: Permanently revokes an API key. This action cannot be undone. tags: - Authentication security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '204': description: API key revoked '404': description: API key not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/issuers: get: summary: List Issuers description: Returns all issuers for the authenticated tenant. tags: - Issuers security: - APIKey: [] - BearerAuth: [] responses: '200': description: List of issuers content: application/json: schema: type: array items: $ref: '#/components/schemas/Issuer' post: summary: Create Issuer description: Registers a new issuer. Newly created issuers start in PENDING status. tags: - Issuers security: - APIKey: [] - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - name - domain properties: name: type: string domain: type: string example: name: Acme University domain: acme.edu responses: '201': description: Issuer created content: application/json: schema: $ref: '#/components/schemas/Issuer' '409': description: Issuer with this domain already exists content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: CONFLICT message: Issuer with domain acme.edu already exists http_status: 409 /v1/issuers/{id}: get: summary: Get Issuer description: Returns details for a specific issuer. tags: - Issuers security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Issuer details content: application/json: schema: $ref: '#/components/schemas/Issuer' '404': description: Issuer not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/issuers/{id}/trust: post: summary: Mark Issuer Trusted description: Marks an issuer as trusted within the tenant's trust registry. tags: - Issuers security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Issuer marked as trusted '404': description: Issuer not found requestBody: &id001 required: false content: application/json: schema: type: object properties: reason: type: string description: Optional reason or note for this action /v1/issuers/{id}/keys: get: summary: List Issuer Keys description: Returns all cryptographic keys registered for an issuer. tags: - Keys security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: List of keys content: application/json: schema: type: array items: $ref: '#/components/schemas/Key' post: summary: Register Key description: Registers a new cryptographic key for an issuer. Supports ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512, and Ed25519. tags: - Keys security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - kid - algorithm - public_key properties: kid: type: string algorithm: $ref: '#/components/schemas/SigningAlgorithm' public_key: type: string description: Base64-encoded public key expires_at: type: string format: date-time example: kid: es256-key-1 algorithm: ES256 public_key: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE... responses: '201': description: Key registered content: application/json: schema: $ref: '#/components/schemas/Key' '400': description: Invalid algorithm or key format content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: VALIDATION_ERROR message: 'Unsupported algorithm. Must be one of: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512, Ed25519' http_status: 400 /v1/attestations: get: summary: List Attestations description: Returns attestations for the authenticated tenant with pagination. tags: - Attestations security: - APIKey: [] parameters: - name: issuer_id in: query schema: type: string format: uuid - name: limit in: query schema: type: integer default: 50 maximum: 100 - name: cursor in: query schema: type: string responses: '200': description: List of attestations content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Attestation' next_cursor: type: string post: summary: Mint Attestation description: 'Creates a new cryptographically signed attestation. Use the `Idempotency-Key` header to ensure safe retries. ' tags: - Attestations security: - APIKey: [] parameters: - name: Idempotency-Key in: header required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - issuer_id - kid - alg - schema - claims properties: issuer_id: type: string format: uuid description: The UUID of the issuer creating the attestation example: 550e8400-e29b-41d4-a716-446655440000 kid: type: string description: Key identifier for the signing key example: es256-key-1 alg: $ref: '#/components/schemas/SigningAlgorithm' description: Cryptographic algorithm used for signing example: ES256 schema: type: string description: 'Credential schema type (e.g. verifiable-id, passport, degree, aml-kyc). See full list below. ' enum: - verifiable-id - passport - drivers-license - government-id - self-sovereign-id - employment-verification - professional-role - membership-card - professional-certification - license - accreditation - degree - completion-cert - course-credit - transcript - micro-credential - training-completion - medical-license - dea-registration - board-certification - health-credential - vaccination-record - aml-kyc - security-clearance - sam-gov - jurisdiction-approval - attestation-of-will - bank-verification - credit-attestation - income-verification - skill-badge - competency - industry-cert - product-authenticity - chain-of-custody - origin-verification - custom - attestation example: verifiable-id claims: type: object additionalProperties: type: string description: 'The structured claims for this credential. Fields depend on the selected schema. See schema catalogue below. ' example: full_name: '' employee_id: '' department: '' title: '' start_date: '' recipient_email: type: string format: email description: 'Email address of the credential recipient. When provided, the platform sends a notification email with a link to view the attestation on the consumer portal (verify.truthlocks.com). If the recipient does not have a consumer portal account, they receive an invitation to sign up. This enables B2C credential delivery workflows. ' document_hash: type: string description: 'Hex-encoded SHA-256 hash of the document or file being attested. Used for document integrity verification — verifiers can recompute the hash of the original file and compare it against this stored value. If omitted, the system checks for claims.document.sha256 in the payload, and if that is also absent, auto-computes the SHA-256 of the raw payload bytes. For best results, compute the hash client-side before base64url-encoding the payload. ' pack_id: type: string format: uuid description: 'UUID of the verification pack to link this attestation to. The pack must be in ''active'' status. When provided, the pack''s verifications_count is automatically incremented. Use this to organize attestations by verification program and track analytics per pack. ' content_type: type: string description: 'MIME type of the payload. Supported: application/json (default), application/pdf, image/png, image/jpeg, image/webp, image/tiff, video/mp4, video/webm, audio/mpeg, audio/wav, application/octet-stream. Max payload size: 50 MB. ' example: application/json responses: '201': description: Attestation minted content: application/json: schema: $ref: '#/components/schemas/Attestation' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '413': description: Payload too large content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit or quota exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/attestations/mint: post: summary: Mint Attestation description: 'Legacy alias for `POST /v1/attestations`. Kept for backward compatibility and rewritten by the gateway. ' tags: - Attestations security: - APIKey: [] parameters: - name: Idempotency-Key in: header required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - issuer_id - kid - alg - schema - claims properties: issuer_id: type: string format: uuid description: The UUID of the issuer creating the attestation example: 550e8400-e29b-41d4-a716-446655440000 kid: type: string description: Key identifier for the signing key example: es256-key-1 alg: $ref: '#/components/schemas/SigningAlgorithm' description: Cryptographic algorithm used for signing example: ES256 schema: type: string description: 'Credential schema type (e.g. verifiable-id, passport, degree, aml-kyc). See full list below. ' enum: - verifiable-id - passport - drivers-license - government-id - self-sovereign-id - employment-verification - professional-role - membership-card - professional-certification - license - accreditation - degree - completion-cert - course-credit - transcript - micro-credential - training-completion - medical-license - dea-registration - board-certification - health-credential - vaccination-record - aml-kyc - security-clearance - sam-gov - jurisdiction-approval - attestation-of-will - bank-verification - credit-attestation - income-verification - skill-badge - competency - industry-cert - product-authenticity - chain-of-custody - origin-verification - custom - attestation example: verifiable-id claims: type: object additionalProperties: type: string description: 'The structured claims for this credential. Fields depend on the selected schema. See schema catalogue below. ' example: full_name: '' employee_id: '' department: '' title: '' start_date: '' recipient_email: type: string format: email description: 'Email address of the credential recipient. When provided, the platform sends a notification email with a link to view the attestation on the consumer portal (verify.truthlocks.com). If the recipient does not have a consumer portal account, they receive an invitation to sign up. This enables B2C credential delivery workflows. ' document_hash: type: string description: 'Hex-encoded SHA-256 hash of the document or file being attested. Used for document integrity verification — verifiers can recompute the hash of the original file and compare it against this stored value. If omitted, the system checks for claims.document.sha256 in the payload, and if that is also absent, auto-computes the SHA-256 of the raw payload bytes. For best results, compute the hash client-side before base64url-encoding the payload. ' pack_id: type: string format: uuid description: 'UUID of the verification pack to link this attestation to. The pack must be in ''active'' status. When provided, the pack''s verifications_count is automatically incremented. Use this to organize attestations by verification program and track analytics per pack. ' content_type: type: string description: 'MIME type of the payload. Supported: application/json (default), application/pdf, image/png, image/jpeg, image/webp, image/tiff, video/mp4, video/webm, audio/mpeg, audio/wav, application/octet-stream. Max payload size: 50 MB. ' example: application/json responses: '201': description: Attestation minted content: application/json: schema: $ref: '#/components/schemas/Attestation' example: id: 660e8400-e29b-41d4-a716-446655440001 issuer_id: 550e8400-e29b-41d4-a716-446655440000 kid: ed-key-1 status: VALID log_index: 42 created_at: '2026-01-13T12:00:00Z' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '413': description: Payload too large content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: PAYLOAD_TOO_LARGE message: Request body exceeds maximum size of 1MB http_status: 413 '429': description: Rate limit or quota exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded http_status: 429 retry_after_ms: 60000 /v1/attestations/{id}: get: summary: Get Attestation description: Returns details for a specific attestation. tags: - Attestations security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Attestation details content: application/json: schema: $ref: '#/components/schemas/Attestation' '404': description: Attestation not found /v1/attestations/{id}/proof-bundle: get: summary: Get Proof Bundle description: 'Returns a complete proof bundle for offline verification. Includes: - The attestation itself - Issuer information - Public key used for signing - Transparency log inclusion proof - Signed tree head ' tags: - Verification security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Proof bundle content: application/json: schema: $ref: '#/components/schemas/ProofBundle' '404': description: Attestation not found /v1/attestations/{id}/revoke: post: summary: Revoke Attestation description: 'Revokes an attestation, marking it as invalid for future verification. This action is recorded in the transparency log and cannot be undone. ' tags: - Attestations security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: reason: type: string description: Optional reason for revocation example: reason: Certificate holder no longer employed responses: '200': description: Attestation revoked content: application/json: schema: $ref: '#/components/schemas/Attestation' '404': description: Attestation not found '409': description: Attestation already revoked /v1/attestations/{id}/supersede: post: summary: Supersede Attestation description: 'Creates a new attestation that supersedes an existing one. The original attestation is marked as SUPERSEDED. ' tags: - Attestations security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - payload properties: payload: type: object description: Updated payload for the new attestation example: payload: subject: user:12345 claim: verified_email value: newemail@example.com responses: '201': description: New attestation created content: application/json: schema: $ref: '#/components/schemas/Attestation' /v1/verify: post: summary: Verify Attestation description: 'Performs a full cryptographic and status verification of an attestation. ## Verdict Truth Table | Verdict | Valid | Description | |---------|-------|-------------| | VALID | true | Signature correct, attestation active | | REVOKED | false | Attestation explicitly revoked | | SUPERSEDED | false | Replaced by newer attestation | | ALTERED | false | Signature verification failed | | UNKNOWN | false | Attestation not found | ' tags: - Verification security: - APIKey: [] - {} requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VerifyRequest' example: attestation_id: 660e8400-e29b-41d4-a716-446655440001 payload_b64url: eyJzdWJqZWN0IjoiZGlkOnRydXRobG9jazoxMjMiLCJ2ZXJpZmllZCI6dHJ1ZX0 document_hash_hex: a1b2c3d4e5f6... responses: '200': description: Verification result content: application/json: schema: $ref: '#/components/schemas/VerifyResponse' examples: valid: summary: Valid attestation value: verdict: VALID valid: true details: issuer_id: 550e8400-e29b-41d4-a716-446655440000 issuer_name: Acme University log_index: 42 revoked: summary: Revoked attestation value: verdict: REVOKED valid: false details: revoked_at: '2026-01-13T15:00:00Z' reason: Certificate holder no longer employed /v1/governance/issuer-requests: get: summary: List issuer governance requests description: Lists governance requests for issuer approval workflows. tags: - Governance security: - APIKey: [] - BearerAuth: [] responses: '200': description: Requests listed content: application/json: schema: type: object post: summary: Create issuer governance request description: Creates a new governance request for issuer approval/changes. tags: - Governance security: - APIKey: [] - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object responses: '201': description: Request created content: application/json: schema: type: object properties: id: type: string format: uuid status: type: string created_at: type: string format: date-time /v1/governance/issuer-requests/{requestId}: get: summary: Get issuer governance request description: Retrieves details of a specific governance request by ID. tags: - Governance security: - APIKey: [] - BearerAuth: [] parameters: - name: requestId in: path required: true schema: type: string format: uuid responses: '200': description: Request details content: application/json: schema: type: object properties: id: type: string format: uuid status: type: string created_at: type: string format: date-time '404': description: Request not found /v1/governance/issuer-requests/{requestId}/approve: post: summary: Approve governance request description: Marks a governance request as approved. tags: - Governance security: - APIKey: [] - BearerAuth: [] parameters: - name: requestId in: path required: true schema: type: string format: uuid responses: '200': description: Request approved content: application/json: schema: type: object properties: success: type: boolean message: type: string '403': description: Permission denied '404': description: Request not found requestBody: *id001 /v1/governance/issuer-requests/{requestId}/execute: post: summary: Execute approved governance request description: Executes a previously approved governance request. tags: - Governance security: - APIKey: [] - BearerAuth: [] parameters: - name: requestId in: path required: true schema: type: string format: uuid responses: '200': description: Request executed content: application/json: schema: type: object properties: success: type: boolean message: type: string '403': description: Permission denied '404': description: Request not found requestBody: *id001 /v1/orgs: get: summary: List Organizations description: Returns organizations for the authenticated tenant. tags: - Identity security: - APIKey: [] - BearerAuth: [] responses: '200': description: List of organizations content: application/json: schema: type: array items: $ref: '#/components/schemas/Organization' /v1/users: get: summary: List Users description: Returns users for the authenticated organization. tags: - Identity security: - APIKey: [] - BearerAuth: [] responses: '200': description: List of users content: application/json: schema: type: array items: $ref: '#/components/schemas/User' post: summary: Invite User description: Invites a new user to the organization. tags: - Identity security: - APIKey: [] - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - email - role_id properties: email: type: string format: email name: type: string role_id: type: string format: uuid responses: '201': description: User invited content: application/json: schema: $ref: '#/components/schemas/User' /v1/roles: get: summary: List Roles description: Returns available roles for the organization. tags: - Identity security: - APIKey: [] - BearerAuth: [] responses: '200': description: List of roles content: application/json: schema: type: array items: $ref: '#/components/schemas/Role' /v1/audit: get: summary: Query Audit Events description: Returns audit events for the authenticated tenant. tags: - Audit security: - APIKey: [] - BearerAuth: [] parameters: - name: actor_id in: query schema: type: string - name: action in: query schema: type: string - name: resource_type in: query schema: type: string - name: from in: query schema: type: string format: date-time - name: to in: query schema: type: string format: date-time - name: limit in: query schema: type: integer default: 50 responses: '200': description: Audit events content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/AuditEvent' next_cursor: type: string /v1/platform/tenants: get: summary: List Tenants description: Returns all tenants. Requires platform admin privileges. tags: - Platform security: - APIKey: [] - BearerAuth: [] responses: '200': description: List of tenants content: application/json: schema: type: array items: $ref: '#/components/schemas/Tenant' '403': description: Platform admin privileges required /v1/platform/tenants/{id}/suspend: post: summary: Suspend Tenant description: Suspends a tenant. All API operations by this tenant will be blocked. tags: - Platform security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: reason: type: string responses: '200': description: Tenant suspended '403': description: Platform admin privileges required '404': description: Tenant not found /v1/platform/tenants/{id}/reinstate: post: summary: Reinstate Tenant description: Reinstates a suspended tenant. tags: - Platform security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Tenant reinstated '403': description: Platform admin privileges required '404': description: Tenant not found requestBody: *id001 /v1/platform/tenants/{id}/approve: post: summary: Approve Tenant description: Approves a tenant for onboarding (default) or direct activation (override). tags: - Platform security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: override: type: boolean description: If true, approve directly to ACTIVE. reason: type: string responses: '200': description: Tenant approved '409': description: Invalid transition '404': description: Tenant not found /v1/platform/review/issuer-applications: get: summary: List issuer applications for platform review description: Returns a paginated list of issuer applications pending platform review. tags: - Platform Review security: - APIKey: [] - BearerAuth: [] parameters: - name: status in: query schema: type: string enum: - DRAFT - SUBMITTED - IN_REVIEW - APPROVED - REJECTED - SUSPENDED - name: q in: query schema: type: string - name: limit in: query schema: type: integer default: 20 - name: offset in: query schema: type: integer default: 0 responses: '200': description: Review queue response content: application/json: schema: type: object /v1/platform/review/issuer-applications/{id}: get: summary: Get issuer application for review description: Retrieves full details of a specific issuer application for review. tags: - Platform Review security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Application details content: application/json: schema: type: object properties: id: type: string format: uuid status: type: string created_at: type: string format: date-time '404': description: Application not found /v1/platform/review/issuer-applications/{id}/approve: post: summary: Approve issuer application description: Approves an issuer application after platform review. tags: - Platform Review security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: reason: type: string notes: type: string responses: '200': description: Application approved content: application/json: schema: type: object properties: success: type: boolean message: type: string /v1/platform/review/issuer-applications/{id}/reject: post: summary: Reject issuer application description: Rejects an issuer application with optional reason. tags: - Platform Review security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Application rejected content: application/json: schema: type: object properties: success: type: boolean message: type: string requestBody: *id001 /v1/platform/review/issuer-applications/{id}/request-changes: post: summary: Request changes on issuer application description: Requests changes on an issuer application before approval. tags: - Platform Review security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Changes requested content: application/json: schema: type: object properties: success: type: boolean message: type: string requestBody: *id001 /v1/platform/review/issuer-applications/{id}/suspend: post: summary: Suspend issuer application description: Suspends an approved issuer application. tags: - Platform Review security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Application suspended content: application/json: schema: type: object properties: success: type: boolean message: type: string requestBody: &id002 required: false content: application/json: schema: type: object properties: reason: type: string description: Reason for revocation /v1/platform/review/issuer-applications/{id}/reinstate: post: summary: Reinstate issuer application description: Reinstates a previously suspended issuer application. tags: - Platform Review security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Application reinstated content: application/json: schema: type: object properties: success: type: boolean message: type: string requestBody: *id001 /v1/tenants/me: get: summary: Get current tenant profile description: Retrieves the authenticated tenant's profile and settings. tags: - Tenant Console security: - APIKey: [] - BearerAuth: [] responses: '200': description: Tenant profile content: application/json: schema: $ref: '#/components/schemas/Tenant' patch: summary: Update current tenant profile description: Updates fields on the authenticated tenant's profile. tags: - Tenant Console security: - APIKey: [] - BearerAuth: [] requestBody: content: application/json: schema: type: object responses: '200': description: Tenant updated content: application/json: schema: $ref: '#/components/schemas/Tenant' /v1/tenants/me/activate: post: summary: Activate tenant after onboarding description: Transitions the tenant from onboarding to active status. tags: - Tenant Console security: - APIKey: [] - BearerAuth: [] responses: '200': description: Tenant activated content: application/json: schema: type: object properties: success: type: boolean message: type: string '409': description: Invalid transition '412': description: Prerequisites not met requestBody: *id001 /healthz: get: summary: Health Check description: Returns service health status. No authentication required. tags: - Health responses: '200': description: Service is healthy content: application/json: schema: type: object properties: status: type: string enum: - ok example: status: ok /readyz: get: summary: Readiness Check description: Returns service readiness. No authentication required. tags: - Health responses: '200': description: Service is ready content: application/json: schema: type: object properties: status: type: string enum: - ready '503': description: Service not ready content: application/json: schema: type: object properties: status: type: string enum: - not_ready /v1/attestation-packs: get: summary: List Verification Packs description: Returns all verification packs for the authenticated tenant, including built-in enterprise templates and custom packs. tags: - Attestations security: - APIKey: [] responses: '200': description: List of verification packs content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string format: uuid tenant_id: type: string format: uuid name: type: string description: type: string category: type: string region: type: string status: type: string enum: - active - inactive - archived is_template: type: boolean verifications_count: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time total: type: integer '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' post: summary: Create Verification Pack description: Creates a new custom verification pack for the tenant. tags: - Attestations security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: type: string category: type: string region: type: string example: name: KYC Identity Verification description: Know Your Customer identity proofing package category: Identity region: Global responses: '201': description: Pack created content: application/json: schema: type: object properties: id: type: string format: uuid '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/attestation-packs/{id}: get: summary: Get Verification Pack description: Returns details of a specific verification pack. tags: - Attestations security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Pack details content: application/json: schema: type: object '404': description: Pack not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' put: summary: Update Verification Pack description: Updates a verification pack's name, description, or configuration. tags: - Attestations security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: type: string category: type: string responses: '200': description: Pack updated content: application/json: schema: type: object /v1/attestation-packs/{id}/status: put: summary: Update Verification Pack Status description: Activates, deactivates, or archives a verification pack. tags: - Attestations security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - status properties: status: type: string enum: - active - inactive - archived responses: '200': description: Status updated content: application/json: schema: type: object /v1/consumer/signup: post: summary: Consumer Signup description: Creates a new consumer account. No authentication required. tags: - Consumer requestBody: required: true content: application/json: schema: type: object required: - email - password - name properties: email: type: string format: email password: type: string format: password name: type: string signup_type: type: string description: Set to 'tenant' for console signups company_name: type: string responses: '201': description: Account created content: application/json: schema: type: object properties: user_id: type: string format: uuid tenant_id: type: string format: uuid session_token: type: string /v1/consumer/login: post: summary: Consumer Login description: Authenticates a consumer and returns a session token. No API key required. tags: - Consumer requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email password: type: string format: password example: email: user@example.com password: password123 responses: '200': description: Login successful content: application/json: schema: type: object properties: session_token: type: string user: type: object properties: id: type: string format: uuid email: type: string name: type: string realm: type: string /v1/consumer/inbox: get: summary: Consumer Inbox description: Returns pending credential deliveries for the authenticated consumer. tags: - Consumer security: - APIKey: [] - BearerAuth: [] responses: '200': description: Inbox items content: application/json: schema: type: object properties: items: type: array items: type: object total: type: integer /v1/consumer/inbox/deliver: post: summary: Deliver Credential to Consumer description: Delivers an attestation to a consumer's inbox via email address. Requires API key (issuer-facing). tags: - Consumer security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - attestation_id - recipient_email properties: attestation_id: type: string format: uuid recipient_email: type: string format: email responses: '200': description: Delivery queued content: application/json: schema: type: object properties: delivery_id: type: string format: uuid status: type: string /v1/consumer/mint: post: summary: Protect Content (Consumer Mint) description: Mint a cryptographic attestation for content you want to protect. Your personal issuer and signing key are resolved automatically. Hash the content client-side (SHA-256) and submit the hash with file metadata. tags: - Consumer security: - APIKey: [] - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - content_hash properties: content_hash: type: string description: SHA-256 hash of the file content, computed client-side. title: type: string description: Human-readable title for the protection. description: type: string description: Optional description of the protected content. content_type: type: string description: MIME type of the content (e.g. image/png). file_name: type: string description: Original file name including extension. file_size: type: integer description: File size in bytes. category: type: string enum: - code - research - design - media - dataset - ai-output - writing - digital-art - other description: Content category. Defaults to other. ai_metadata: type: object description: Optional AI-extracted metadata object. visibility: type: string enum: - public - private description: Whether the protection appears on your public portfolio. Defaults to private. responses: '201': description: Content protected content: application/json: schema: type: object properties: protection_id: type: string format: uuid attestation_id: type: string format: uuid verify_url: type: string format: uri share_url: type: string format: uri content_hash: type: string description: SHA-256 hash echoed back from the request. protected_at: type: string format: date-time description: Timestamp when the content was protected (RFC 3339). status: type: string enum: - protected '400': description: Missing required field '401': description: Unauthorized '429': description: Monthly protection limit reached /v1/public/proof/{attestation_id}: get: summary: Get Proof Page Metadata description: Returns metadata for a consumer content protection, used to render public proof pages. No authentication required. tags: - Consumer parameters: - name: attestation_id in: path required: true schema: type: string format: uuid description: The attestation ID linked to the consumer protection. responses: '200': description: Proof page metadata content: application/json: schema: type: object properties: attestation_id: type: string format: uuid title: type: string description: type: string content_type: type: string description: MIME type of the protected content. file_name: type: string file_size: type: integer description: File size in bytes. content_hash: type: string description: SHA-256 hash of the protected content. category: type: string protected_at: type: string format: date-time description: Timestamp when the content was protected (RFC 3339). '400': description: Invalid attestation ID '404': description: Protection not found /v1/consumer/protections: get: summary: List Consumer Protections description: Returns all content protections (attestations) for the authenticated consumer. tags: - Consumer security: - APIKey: [] - BearerAuth: [] responses: '200': description: List of protections content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Attestation' total: type: integer /v1/consumer/portfolio/{username}: get: summary: Public Portfolio description: Returns the public portfolio for a consumer by username. No authentication required. tags: - Consumer parameters: - name: username in: path required: true schema: type: string responses: '200': description: Public portfolio content: application/json: schema: type: object properties: username: type: string display_name: type: string items: type: array items: type: object '404': description: Portfolio not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/consumer/stats: get: summary: Consumer Stats description: Returns statistics for the authenticated consumer's protections and portfolio. tags: - Consumer security: - APIKey: [] - BearerAuth: [] responses: '200': description: Consumer statistics content: application/json: schema: type: object properties: total_protections: type: integer total_verifications: type: integer portfolio_views: type: integer /v1/consumer/privacy/export: post: summary: Request Data Export description: Request a full export of all data associated with your account. Exports are delivered in JSON format and include your profile, protections, credentials, and activity history. tags: - Consumer security: - APIKey: [] - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: format: type: string enum: - json description: Export format. Currently only json is supported. reason: type: string description: Optional reason for the export request, recorded in the audit log. responses: '201': description: Export requested content: application/json: schema: type: object properties: job_id: type: string status: type: string enum: - PENDING created_at: type: string format: date-time '401': description: Unauthorized '429': description: An export is already in progress /v1/consumer/privacy/delete-account: post: summary: Request Account Deletion description: Request permanent deletion of your account and all associated data. Deletion requests are processed within 30 days in compliance with data protection regulations. tags: - Consumer security: - APIKey: [] - BearerAuth: [] requestBody: required: false content: application/json: schema: type: object properties: reason: type: string description: Optional reason for the deletion request, recorded in the audit log. responses: '201': description: Deletion requested content: application/json: schema: type: object properties: job_id: type: string status: type: string enum: - PENDING created_at: type: string format: date-time '401': description: Unauthorized '409': description: A deletion request is already pending /v1/consumer/privacy/jobs: get: summary: List Privacy Jobs description: List all privacy requests for the authenticated consumer. Returns export and deletion jobs sorted by creation date with real-time status updates. tags: - Consumer security: - APIKey: [] - BearerAuth: [] responses: '200': description: List of privacy jobs content: application/json: schema: type: array items: type: object properties: id: type: string job_type: type: string enum: - EXPORT - DELETE target_type: type: string status: type: string enum: - PENDING - APPROVED - PROCESSING - COMPLETED - FAILED - EXPIRED created_at: type: string format: date-time updated_at: type: string format: date-time reason: type: string result: type: object properties: download_url: type: string format: uri expires_at: type: string format: date-time '401': description: Unauthorized /v1/consumer/api-keys: get: summary: List Consumer API Keys description: Returns all API keys for the authenticated consumer. Secrets are never returned in list responses. tags: - Consumer security: - BearerAuth: [] responses: '200': description: List of consumer API keys content: application/json: schema: type: array items: $ref: '#/components/schemas/ConsumerAPIKey' example: - key_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 name: My integration key prefix: tlk_abcd1234 status: active scopes: - consumer:read - consumer:write - attestations:mint - attestations:read - verify:read created_at: '2026-03-01T12:00:00Z' expires_at: '2026-05-30T12:00:00Z' last_used_at: '2026-03-20T09:15:00Z' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: AUTH_REQUIRED message: Authentication required http_status: 401 post: summary: Create Consumer API Key description: Creates a new personal API key. The full secret is returned once and cannot be retrieved again. Consumers may hold up to 5 active keys. Keys expire after 90 days. tags: - Consumer security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: A human-readable label for the key example: name: CI pipeline key responses: '201': description: API key created. The secret is shown only in this response. content: application/json: schema: allOf: - $ref: '#/components/schemas/ConsumerAPIKey' - type: object properties: secret: type: string description: Full API key value (shown once) example: key_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 name: CI pipeline key prefix: tlk_abcd1234 status: active scopes: - consumer:read - consumer:write - attestations:mint - attestations:read - verify:read secret: tlk_abcd1234abcd5678ef901234abcd5678ef901234abcd5678ef901234abcd5678 created_at: '2026-03-25T14:30:00Z' expires_at: '2026-06-23T14:30:00Z' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: VALIDATION_ERROR message: Maximum of 5 active API keys reached. Revoke an existing key first. http_status: 400 '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/consumer/api-keys/{id}/revoke: post: summary: Revoke Consumer API Key description: Permanently revokes a consumer API key. All requests using this key will immediately return 401. tags: - Consumer security: - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid description: The key_id of the API key to revoke responses: '200': description: Key revoked content: application/json: schema: type: object properties: message: type: string example: message: API key revoked '404': description: API key not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: NOT_FOUND message: API key not found http_status: 404 requestBody: *id002 /v1/issuers/{id}/events: get: summary: Issuer Event History description: Returns the event history for a specific issuer. tags: - Issuers security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Event list content: application/json: schema: type: object properties: items: type: array items: type: object properties: event_type: type: string timestamp: type: string format: date-time details: type: object /v1/issuers/keys/{kid}/rotate: post: summary: Rotate Issuer Key description: Rotates a cryptographic key, creating a new key and disabling the old one. Optionally specify a new algorithm for the rotated key. tags: - Keys security: - APIKey: [] parameters: - name: kid in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: alg: $ref: '#/components/schemas/SigningAlgorithm' description: Algorithm for the new rotated key. Defaults to the same algorithm as the existing key. responses: '200': description: Key rotated content: application/json: schema: $ref: '#/components/schemas/Key' /v1/issuers/keys/{kid}/compromise: post: summary: Report Key Compromise description: Reports a key as compromised. Immediately disables the key and flags all attestations signed with it for review. tags: - Keys security: - APIKey: [] parameters: - name: kid in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: reason: type: string responses: '200': description: Key marked as compromised content: application/json: schema: type: object properties: kid: type: string status: type: string affected_attestations: type: integer /v1/audit/exports: post: summary: Create Audit Export description: Creates an asynchronous audit event export job. tags: - Audit security: - APIKey: [] requestBody: content: application/json: schema: type: object properties: start_date: type: string format: date-time end_date: type: string format: date-time format: type: string enum: - csv - json responses: '202': description: Export job created content: application/json: schema: type: object properties: export_id: type: string format: uuid status: type: string /v1/orgs/{id}: get: summary: Get Organization description: Returns details for a specific organization. tags: - Identity security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Organization details content: application/json: schema: $ref: '#/components/schemas/Organization' '404': description: Organization not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/platform/issuers/{id}/suspend: post: summary: Suspend Issuer (Platform Admin) description: Suspends an issuer at the platform level. Requires platform admin privileges. tags: - Platform security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: reason: type: string responses: '200': description: Issuer suspended content: application/json: schema: type: object /v1/risk/signals: post: summary: Ingest Risk Signal description: 'Submit a risk signal for a specific entity. Risk signals are scored observations from fraud-detection sources such as device fingerprinting, IP reputation services, email verification providers, or your own internal rules engine. Each signal is stored with full tenant isolation (row-level security) and can be used to inform downstream risk decisions. ' tags: - Risk security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - source - signal_type - score - entity_type - entity_id properties: source: type: string description: Origin of the signal (e.g. device_fingerprint, ip_reputation, email_verification, document_analysis, behavioral) example: device_fingerprint signal_type: type: string description: Classification of the risk signal example: velocity_anomaly score: type: number format: float minimum: 0 maximum: 1 description: Risk score between 0 (no risk) and 1 (highest risk) example: 0.85 details: type: object additionalProperties: true description: Arbitrary metadata to attach to the signal example: ip: 203.0.113.42 country: US reason: multiple_accounts_same_device entity_type: type: string description: The type of entity this signal relates to enum: - user - device - ip - document - session example: user entity_id: type: string description: Identifier of the entity being evaluated example: usr_8f14e45f responses: '201': description: Risk signal ingested content: application/json: schema: $ref: '#/components/schemas/RiskSignal' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' get: summary: List Risk Signals description: 'Returns risk signals for the authenticated tenant with pagination. Filter by source, signal type, entity, or minimum score. ' tags: - Risk security: - APIKey: [] parameters: - name: source in: query description: Filter by signal source schema: type: string - name: signal_type in: query description: Filter by signal type schema: type: string - name: entity_type in: query description: Filter by entity type schema: type: string enum: - user - device - ip - document - session - name: entity_id in: query description: Filter by entity ID schema: type: string - name: min_score in: query description: Return only signals with score >= this value schema: type: number format: float minimum: 0 maximum: 1 - name: limit in: query schema: type: integer default: 50 maximum: 100 - name: cursor in: query schema: type: string responses: '200': description: List of risk signals content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/RiskSignal' next_cursor: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/signals/{id}: get: summary: Get Risk Signal description: Retrieves a specific risk signal by its unique ID. tags: - Risk security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Risk signal details content: application/json: schema: $ref: '#/components/schemas/RiskSignal' '404': description: Risk signal not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/api-keys/{id}/revoke: post: summary: Revoke API Key description: Permanently revokes an API key. This action cannot be undone. tags: - Authentication security: - APIKey: [] - BearerAuth: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Key revoked content: application/json: schema: type: object properties: id: type: string format: uuid status: type: string enum: - REVOKED requestBody: *id002 /v1/agents: post: operationId: maip.agents.register summary: Register Agent description: 'Register a new machine agent identity. Returns the agent record including a generated public key and initial trust score. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - agent_type - display_name properties: agent_type: type: string enum: - orchestrator - worker - inference - pipeline - service - bot - llm description: Classification of the agent display_name: type: string maxLength: 256 description: Human-readable agent name description: type: string description: Free-text description of the agent purpose scopes: type: array items: type: string description: Permission scopes granted to the agent metadata: type: object additionalProperties: true description: Arbitrary key-value metadata example: agent_type: orchestrator display_name: Data Pipeline Orchestrator description: Coordinates ETL pipeline agents scopes: - datasets:read - datasets:write - models:read metadata: team: data-engineering responses: '201': description: Agent registered content: application/json: schema: $ref: '#/components/schemas/MaipAgent' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' get: operationId: maip.agents.list summary: List Agents description: Returns a paginated list of registered machine agents filtered by optional criteria. tags: - Machine Identity security: - APIKey: [] parameters: - name: limit in: query schema: type: integer default: 25 minimum: 1 maximum: 100 description: Maximum number of agents to return - name: offset in: query schema: type: integer default: 0 minimum: 0 description: Number of agents to skip - name: status in: query schema: type: string enum: - active - suspended - revoked description: Filter by agent status - name: agent_type in: query schema: type: string enum: - orchestrator - worker - inference - pipeline - service - bot - llm description: Filter by agent type responses: '200': description: Paginated list of agents content: application/json: schema: $ref: '#/components/schemas/MaipAgentList' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/agents/{agentId}: get: operationId: maip.agents.get summary: Get Agent description: Returns the full agent record including keys, trust score, and session count. tags: - Machine Identity security: - APIKey: [] parameters: - name: agentId in: path required: true schema: type: string format: uuid description: Agent identifier responses: '200': description: Agent details content: application/json: schema: $ref: '#/components/schemas/MaipAgent' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' patch: operationId: maip.agents.update summary: Update Agent description: Update mutable fields on an existing agent identity. tags: - Machine Identity security: - APIKey: [] parameters: - name: agentId in: path required: true schema: type: string format: uuid description: Agent identifier requestBody: required: true content: application/json: schema: type: object properties: display_name: type: string maxLength: 256 description: type: string scopes: type: array items: type: string metadata: type: object additionalProperties: true responses: '200': description: Agent updated content: application/json: schema: $ref: '#/components/schemas/MaipAgent' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/agents/{agentId}/suspend: post: operationId: maip.agents.suspend summary: Suspend Agent description: 'Suspends an agent, preventing it from creating new sessions or invoking tools. Existing sessions remain active until they expire. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: agentId in: path required: true schema: type: string format: uuid description: Agent identifier requestBody: required: true content: application/json: schema: type: object required: - reason properties: reason: type: string description: Human-readable reason for suspension responses: '200': description: Agent suspended content: application/json: schema: $ref: '#/components/schemas/MaipAgent' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/agents/{agentId}/revoke: post: operationId: maip.agents.revoke summary: Revoke Agent description: 'Permanently revokes an agent identity. All active sessions are terminated and the agent can no longer authenticate. This action cannot be undone. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: agentId in: path required: true schema: type: string format: uuid description: Agent identifier requestBody: required: true content: application/json: schema: type: object required: - reason properties: reason: type: string description: Human-readable reason for revocation responses: '200': description: Agent revoked content: application/json: schema: $ref: '#/components/schemas/MaipAgent' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/agents/{agentId}/kill: post: operationId: maip.agents.kill summary: Emergency Kill Switch description: 'Emergency kill switch that immediately revokes the agent, terminates all active sessions, and optionally cascades to downstream delegated agents. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: agentId in: path required: true schema: type: string format: uuid description: Agent identifier requestBody: required: true content: application/json: schema: type: object required: - reason properties: reason: type: string description: Reason for emergency kill cascade: type: boolean default: false description: If true, also kill all agents this agent delegated to responses: '200': description: Agent killed content: application/json: schema: type: object properties: agent: $ref: '#/components/schemas/MaipAgent' terminated_sessions: type: integer description: Number of sessions terminated '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/scopes: get: operationId: maip.scopes.list summary: List Scopes description: Returns all permission scopes available to the authenticated tenant, including platform built-ins and tenant custom scopes. tags: - Machine Identity security: - APIKey: [] parameters: - name: category in: query required: false schema: type: string enum: - data - model - tool - agent - admin - receipt - custom description: Filter scopes by category responses: '200': description: Available scopes content: application/json: schema: type: array items: type: object properties: id: type: string format: uuid tenant_id: type: string format: uuid nullable: true scope: type: string resource: type: string action: type: string display_name: type: string description: type: string category: type: string is_builtin: type: boolean created_at: type: string format: date-time '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' post: operationId: maip.scopes.create summary: Create Scope description: Creates a custom tenant-scoped permission scope for fine-grained agent access control. tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - resource - action properties: resource: type: string description: Resource component of the scope (e.g. "crm", "payment") action: type: string description: Action component of the scope (e.g. "read", "approve", "*") display_name: type: string description: Human-readable name for the scope description: type: string description: Detailed description of what the scope grants category: type: string description: Organizational category (defaults to "custom") example: resource: crm action: contact.enrich display_name: CRM Contact Enrichment description: Allows agents to enrich CRM contact records category: integration responses: '201': description: Scope created content: application/json: schema: type: object properties: id: type: string format: uuid tenant_id: type: string format: uuid scope: type: string resource: type: string action: type: string display_name: type: string description: type: string category: type: string is_builtin: type: boolean created_at: type: string format: date-time '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: Scope already exists content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/agent-sessions: post: operationId: maip.sessions.create summary: Create Session description: 'Creates a short-lived session for an agent. The session token is returned once and must be used in subsequent requests within the TTL window. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - agent_id properties: agent_id: type: string format: uuid description: Agent to create the session for scopes: type: array items: type: string description: Scopes for this session (must be subset of agent scopes) ttl_seconds: type: integer minimum: 60 maximum: 86400 default: 3600 description: Session time-to-live in seconds metadata: type: object additionalProperties: true example: agent_id: 550e8400-e29b-41d4-a716-446655440000 scopes: - datasets:read ttl_seconds: 1800 responses: '201': description: Session created content: application/json: schema: $ref: '#/components/schemas/MaipSession' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' get: operationId: maip.sessions.list summary: List Sessions description: Returns a paginated list of sessions optionally filtered by agent or status. tags: - Machine Identity security: - APIKey: [] parameters: - name: agent_id in: query schema: type: string format: uuid description: Filter sessions by agent - name: status in: query schema: type: string enum: - active - terminated - expired description: Filter by session status - name: limit in: query schema: type: integer default: 25 minimum: 1 maximum: 100 - name: offset in: query schema: type: integer default: 0 minimum: 0 responses: '200': description: Paginated list of sessions content: application/json: schema: $ref: '#/components/schemas/MaipSessionList' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/agent-sessions/{sessionId}: delete: operationId: maip.sessions.terminate summary: Terminate Session description: Immediately terminates an active session, invalidating the session token. tags: - Machine Identity security: - APIKey: [] parameters: - name: sessionId in: path required: true schema: type: string format: uuid description: Session identifier requestBody: required: true content: application/json: schema: type: object required: - reason properties: reason: type: string description: Reason for termination responses: '200': description: Session terminated content: application/json: schema: $ref: '#/components/schemas/MaipSession' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Session not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/tools: post: operationId: maip.tools.register summary: Register Tool description: 'Registers a callable tool that agents can invoke. The tool schema defines the expected input arguments using JSON Schema. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - name - agent_id properties: name: type: string description: Unique tool name description: type: string description: Human-readable tool description schema: type: object additionalProperties: true description: JSON Schema defining the tool input arguments agent_id: type: string format: uuid description: Owning agent example: name: sentiment-analysis description: Analyzes text sentiment schema: type: object properties: text: type: string required: - text agent_id: 550e8400-e29b-41d4-a716-446655440000 responses: '201': description: Tool registered content: application/json: schema: $ref: '#/components/schemas/MaipTool' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/tools/{toolName}/invoke: post: operationId: maip.tools.invoke summary: Invoke Tool description: 'Invokes a registered tool within a session context. Returns the result along with a receipt ID for auditability and execution timing. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: toolId in: path required: true schema: type: string format: uuid description: Tool identifier requestBody: required: true content: application/json: schema: type: object required: - session_id - arguments properties: session_id: type: string format: uuid description: Active session to invoke under arguments: type: object additionalProperties: true description: Tool input arguments matching the tool schema responses: '200': description: Tool invocation result content: application/json: schema: $ref: '#/components/schemas/MaipToolInvocationResult' '400': description: Validation error or schema mismatch content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Tool or session not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/agents/{agentId}/trust-score: get: operationId: maip.agents.trust.get summary: Get Trust Score description: Returns the current trust score and contributing factors for the agent. tags: - Machine Identity security: - APIKey: [] parameters: - name: agentId in: path required: true schema: type: string format: uuid description: Agent identifier responses: '200': description: Trust score content: application/json: schema: $ref: '#/components/schemas/MaipTrustScore' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/trust/compute: post: operationId: maip.agents.trust.compute summary: Recompute Trust Score description: 'Forces an immediate recomputation of the agent trust score using the latest signals. Returns the individual contributing factors. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - agent_id properties: agent_id: type: string description: MAIP agent identifier (e.g. maip:a0000000:01abc...) include_factors: type: boolean default: true description: Whether to include individual factor breakdown responses: '200': description: Recomputed trust score content: application/json: schema: $ref: '#/components/schemas/MaipTrustScore' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/agents/{agentId}/trust-history: get: operationId: maip.agents.trust.history summary: Trust Score History description: Returns historical trust score values over time for trend analysis. tags: - Machine Identity security: - APIKey: [] parameters: - name: agentId in: path required: true schema: type: string format: uuid description: Agent identifier - name: from in: query schema: type: string format: date-time description: Start of time range (ISO 8601) - name: to in: query schema: type: string format: date-time description: End of time range (ISO 8601) - name: limit in: query schema: type: integer default: 50 minimum: 1 maximum: 500 responses: '200': description: Trust score history content: application/json: schema: $ref: '#/components/schemas/MaipTrustHistory' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/witness/request: post: operationId: maip.witness.create summary: Create Witness Request description: 'Creates a witness group requiring a threshold of attestations from specified agents before a claim is considered validated. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - name - required_attestations - agent_ids properties: name: type: string description: Witness group name required_attestations: type: integer minimum: 1 description: Minimum attestations required for consensus agent_ids: type: array items: type: string format: uuid description: Agents eligible to attest example: name: Model Validation Panel required_attestations: 3 agent_ids: - 550e8400-e29b-41d4-a716-446655440000 - 550e8400-e29b-41d4-a716-446655440001 - 550e8400-e29b-41d4-a716-446655440002 - 550e8400-e29b-41d4-a716-446655440003 responses: '201': description: Witness group created content: application/json: schema: $ref: '#/components/schemas/MaipWitnessGroup' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/witness/{witnessId}/attest: post: operationId: maip.witness.attest summary: Submit Attestation description: 'Submits a cryptographic attestation from an agent to a witness group. Each agent may attest only once per group. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: witnessId in: path required: true schema: type: string format: uuid description: Witness group identifier requestBody: required: true content: application/json: schema: type: object required: - agent_id - claim_hash - signature properties: agent_id: type: string format: uuid description: Attesting agent claim_hash: type: string description: SHA-256 hash of the claim being attested signature: type: string description: Ed25519 signature over the claim hash responses: '201': description: Attestation submitted content: application/json: schema: $ref: '#/components/schemas/MaipAttestation' '400': description: Validation error or duplicate attestation content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Witness group not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/witness/{witnessId}/consensus: post: operationId: maip.witness.consensus summary: Check Consensus description: 'Checks whether the witness group has reached the required attestation threshold. Returns the current attestation count and collected signatures. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: witnessId in: path required: true schema: type: string format: uuid description: Witness group identifier responses: '200': description: Consensus status content: application/json: schema: $ref: '#/components/schemas/MaipConsensus' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Witness group not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' requestBody: *id001 /v1/truth/claim: post: operationId: maip.truth.create summary: Create Truth Claim description: 'Creates a new truth claim with supporting evidence. A receipt is generated for auditability and the claim enters a verification pipeline. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - agent_id - claim_type - payload properties: agent_id: type: string format: uuid description: Claiming agent claim_type: type: string description: Classification of the claim (e.g. data_integrity, model_accuracy) payload: type: object additionalProperties: true description: Claim payload evidence: type: array items: type: object additionalProperties: true description: Supporting evidence objects responses: '201': description: Truth claim created content: application/json: schema: $ref: '#/components/schemas/MaipTruthClaim' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/truth/verify: post: operationId: maip.truth.verify summary: Verify Truth Claim description: 'Verifies a previously created truth claim by checking cryptographic proofs, witness attestations, and evidence validity. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - claim_id properties: claim_id: type: string format: uuid description: Claim to verify responses: '200': description: Verification result content: application/json: schema: $ref: '#/components/schemas/MaipTruthVerification' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Claim not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/truth/claims/{claimId}/status: get: operationId: maip.truth.claims.status summary: Get Claim Status description: Returns the current status of a truth claim including attestation progress. tags: - Machine Identity security: - APIKey: [] parameters: - name: claimId in: path required: true schema: type: string format: uuid description: Claim identifier responses: '200': description: Claim status content: application/json: schema: $ref: '#/components/schemas/MaipTruthClaim' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Claim not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/truth/document/verify: post: operationId: maip.truth.document.verify summary: Verify Document Truth description: 'Verifies the truth status of a document by cross-referencing its hash against associated truth claims. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - document_hash - agent_id properties: document_hash: type: string description: SHA-256 hash of the document agent_id: type: string format: uuid description: Requesting agent claim_ids: type: array items: type: string format: uuid description: Specific claims to verify against responses: '200': description: Document verification result content: application/json: schema: $ref: '#/components/schemas/MaipDocumentVerification' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/truth/document/{documentId}: get: operationId: maip.truth.document.get summary: Get Document Verification description: Returns the full verification record for a document including all associated claims. tags: - Machine Identity security: - APIKey: [] parameters: - name: documentId in: path required: true schema: type: string format: uuid description: Document verification identifier responses: '200': description: Document verification details content: application/json: schema: $ref: '#/components/schemas/MaipDocumentVerification' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Document not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/compliance/check: post: operationId: maip.compliance.check summary: Create Compliance Check description: 'Initiates a compliance check for an agent against a specified regulatory framework. Returns findings with severity classifications. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - agent_id - framework properties: agent_id: type: string format: uuid description: Agent to evaluate framework: type: string enum: - soc2 - iso27001 - hipaa - gdpr description: Compliance framework scope: type: object additionalProperties: true description: Scope parameters for the check example: agent_id: 550e8400-e29b-41d4-a716-446655440000 framework: soc2 scope: controls: - CC6.1 - CC6.2 - CC6.3 responses: '201': description: Compliance check created content: application/json: schema: $ref: '#/components/schemas/MaipComplianceCheck' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/compliance/reports: get: operationId: maip.compliance.reports.list summary: List Compliance Reports description: Returns a paginated list of compliance reports filtered by optional criteria. tags: - Machine Identity security: - APIKey: [] parameters: - name: agent_id in: query schema: type: string format: uuid description: Filter by agent - name: framework in: query schema: type: string enum: - soc2 - iso27001 - hipaa - gdpr description: Filter by framework - name: status in: query schema: type: string enum: - pending - passed - failed - partial description: Filter by result status - name: limit in: query schema: type: integer default: 25 minimum: 1 maximum: 100 - name: offset in: query schema: type: integer default: 0 minimum: 0 responses: '200': description: Paginated compliance reports content: application/json: schema: $ref: '#/components/schemas/MaipComplianceReportList' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/agents/{agentId}/anomalies: post: operationId: maip.anomalies.report summary: Report Anomaly description: 'Reports a behavioral or security anomaly detected for an agent. Anomalies are tracked and may affect the agent trust score. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: agentId in: path required: true schema: type: string format: uuid description: Agent identifier requestBody: required: true content: application/json: schema: type: object required: - anomaly_type - severity properties: anomaly_type: type: string description: Classification (e.g. scope_escalation, unusual_volume, auth_failure_burst) severity: type: string enum: - low - medium - high - critical description: Severity classification description: type: string description: Human-readable description of the anomaly evidence: type: object additionalProperties: true description: Structured evidence supporting the anomaly report responses: '201': description: Anomaly reported content: application/json: schema: $ref: '#/components/schemas/MaipAnomaly' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/agents/{agentId}/anomalies/{anomalyId}/resolve: post: operationId: maip.anomalies.resolve summary: Resolve Anomaly description: Marks an anomaly as resolved with a resolution description. tags: - Machine Identity security: - APIKey: [] parameters: - name: agentId in: path required: true schema: type: string format: uuid description: Agent identifier - name: anomalyId in: path required: true schema: type: string format: uuid description: Anomaly identifier requestBody: required: true content: application/json: schema: type: object required: - resolution properties: resolution: type: string description: Resolution type (false_positive, mitigated, accepted_risk, agent_revoked) notes: type: string description: Investigator notes explaining the resolution decision responses: '200': description: Anomaly resolved content: application/json: schema: $ref: '#/components/schemas/MaipAnomaly' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Anomaly not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/datasets/attest: post: operationId: maip.datasets.attest summary: Attest Dataset description: 'Creates a cryptographic attestation for a dataset, recording its hash, format, and provenance on the transparency log. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - name - hash - format - size_bytes - agent_id properties: name: type: string description: Dataset name hash: type: string description: SHA-256 hash of the dataset format: type: string description: Data format (e.g. parquet, csv, jsonl) size_bytes: type: integer format: int64 description: Dataset size in bytes agent_id: type: string format: uuid description: Attesting agent metadata: type: object additionalProperties: true description: Additional dataset metadata example: name: training-data-v3 hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 format: parquet size_bytes: 1073741824 agent_id: 550e8400-e29b-41d4-a716-446655440000 responses: '201': description: Dataset attested content: application/json: schema: $ref: '#/components/schemas/MaipDataset' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/datasets: get: operationId: maip.datasets.list summary: List Attested Datasets description: Returns a paginated list of attested datasets filtered by optional criteria. tags: - Machine Identity security: - APIKey: [] parameters: - name: agent_id in: query schema: type: string format: uuid description: Filter by attesting agent - name: format in: query schema: type: string description: Filter by data format - name: limit in: query schema: type: integer default: 25 minimum: 1 maximum: 100 - name: offset in: query schema: type: integer default: 0 minimum: 0 responses: '200': description: Paginated dataset list content: application/json: schema: $ref: '#/components/schemas/MaipDatasetList' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/datasets/lineage/{datasetId}: get: operationId: maip.datasets.lineage summary: Get Dataset Lineage description: 'Returns the full lineage chain for a dataset showing all transformations, source datasets, and responsible agents. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: datasetId in: path required: true schema: type: string format: uuid description: Dataset identifier responses: '200': description: Dataset lineage content: application/json: schema: $ref: '#/components/schemas/MaipDatasetLineage' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Dataset not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/models/attest: post: operationId: maip.models.attest summary: Attest Model description: 'Creates a cryptographic attestation for a machine learning model, recording its hash, framework, version, and training dataset lineage. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - name - hash - framework - version - agent_id properties: name: type: string description: Model name hash: type: string description: SHA-256 hash of the model weights framework: type: string description: ML framework (e.g. pytorch, tensorflow, onnx) version: type: string description: Model version string agent_id: type: string format: uuid description: Attesting agent training_dataset_ids: type: array items: type: string format: uuid description: IDs of attested training datasets example: name: fraud-detection-v2 hash: a1b2c3d4e5f6789012345678abcdef0123456789abcdef0123456789abcdef01 framework: pytorch version: 2.1.0 agent_id: 550e8400-e29b-41d4-a716-446655440000 training_dataset_ids: - 660e8400-e29b-41d4-a716-446655440000 responses: '201': description: Model attested content: application/json: schema: $ref: '#/components/schemas/MaipModel' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/models/{modelId}/lineage: get: operationId: maip.models.lineage summary: Get Model Lineage description: 'Returns the full lineage for a model including training runs, training datasets, and parent models. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: modelId in: path required: true schema: type: string format: uuid description: Model identifier responses: '200': description: Model lineage content: application/json: schema: $ref: '#/components/schemas/MaipModelLineage' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Model not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/orchestrate/execute: post: operationId: maip.orchestrations.execute summary: Execute Orchestration description: 'Starts an orchestration that coordinates multiple agents to execute a workflow. Each step produces a receipt for full auditability. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - workflow_id - agents properties: workflow_id: type: string format: uuid description: Workflow to execute agents: type: array items: type: string format: uuid description: Agents participating in the orchestration parameters: type: object additionalProperties: true description: Execution parameters responses: '201': description: Orchestration started content: application/json: schema: $ref: '#/components/schemas/MaipOrchestration' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/orchestrate/executions/{orchestrationId}: get: operationId: maip.orchestrations.get summary: Get Orchestration description: Returns the full orchestration record including steps, results, and receipts. tags: - Machine Identity security: - APIKey: [] parameters: - name: orchestrationId in: path required: true schema: type: string format: uuid description: Orchestration identifier responses: '200': description: Orchestration details content: application/json: schema: $ref: '#/components/schemas/MaipOrchestration' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Orchestration not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/orchestrate/llm/inference: post: operationId: maip.orchestrations.llmInference summary: LLM Inference with Receipt description: 'Performs an LLM inference call on behalf of an agent. The call is logged with a receipt including token usage and cost for full auditability. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - model - prompt - agent_id properties: model: type: string description: Model identifier (e.g. gpt-4, claude-3) prompt: type: string description: Input prompt agent_id: type: string format: uuid description: Invoking agent parameters: type: object additionalProperties: true description: Model parameters (temperature, max_tokens, etc.) example: model: claude-3-sonnet prompt: Analyze this dataset for anomalies agent_id: 550e8400-e29b-41d4-a716-446655440000 parameters: temperature: 0.3 max_tokens: 2048 responses: '200': description: Inference result with receipt content: application/json: schema: $ref: '#/components/schemas/MaipLlmInferenceResult' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/orchestrate/workflows: post: operationId: maip.workflows.create summary: Create Workflow description: 'Defines a reusable workflow composed of ordered steps, each assigned to an agent with specific parameters. Workflows can be triggered manually or via configured triggers. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - name - steps properties: name: type: string description: Workflow name steps: type: array items: type: object required: - action - agent_id properties: action: type: string description: Action to perform agent_id: type: string format: uuid description: Agent assigned to this step parameters: type: object additionalProperties: true description: Ordered workflow steps triggers: type: object additionalProperties: true description: Trigger conditions (cron, event, webhook) example: name: Data Quality Pipeline steps: - action: validate_schema agent_id: 550e8400-e29b-41d4-a716-446655440000 parameters: strict: true - action: check_anomalies agent_id: 550e8400-e29b-41d4-a716-446655440001 triggers: cron: 0 */6 * * * responses: '201': description: Workflow created content: application/json: schema: $ref: '#/components/schemas/MaipWorkflow' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/orchestrate/workflows/{workflowId}/execute: post: operationId: maip.workflows.execute summary: Execute Workflow description: 'Triggers execution of a workflow. Supports dry-run mode to preview the execution plan without performing any actions. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: workflowId in: path required: true schema: type: string format: uuid description: Workflow identifier requestBody: required: true content: application/json: schema: type: object properties: parameters: type: object additionalProperties: true description: Runtime parameters for this execution dry_run: type: boolean default: false description: If true, return the execution plan without running it responses: '201': description: Workflow execution started content: application/json: schema: $ref: '#/components/schemas/MaipWorkflowExecution' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Workflow not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/guardrails/check: post: operationId: maip.guardrails.check summary: Check Guardrail description: 'Evaluates an agent action against a set of guardrail rules. Returns whether the action is allowed and any violations detected. A receipt is generated for auditability. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - agent_id - action properties: agent_id: type: string format: uuid description: Agent requesting the action action: type: string description: Action being evaluated (e.g. invoke_tool, access_data) context: type: object additionalProperties: true description: Contextual information for evaluation rules: type: array items: type: string description: Specific rule IDs to evaluate (empty = all rules) example: agent_id: 550e8400-e29b-41d4-a716-446655440000 action: invoke_tool context: tool_name: database-query query: SELECT * FROM users rules: - no-wildcard-queries - pii-access-control responses: '200': description: Guardrail check result content: application/json: schema: $ref: '#/components/schemas/MaipGuardrailResult' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/delegations/cross-tenant/offer: post: operationId: maip.delegations.offer summary: Offer Delegation description: 'Creates a delegation offer from one agent to another, granting a subset of scopes with an optional TTL and conditions. The receiving agent must explicitly accept the delegation. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - from_agent_id - to_agent_id - scopes properties: from_agent_id: type: string format: uuid description: Delegating agent to_agent_id: type: string format: uuid description: Receiving agent scopes: type: array items: type: string description: Scopes to delegate (must be subset of delegating agent scopes) ttl_seconds: type: integer minimum: 60 maximum: 604800 description: Delegation time-to-live in seconds (max 7 days) conditions: type: object additionalProperties: true description: Conditional constraints on the delegation example: from_agent_id: 550e8400-e29b-41d4-a716-446655440000 to_agent_id: 550e8400-e29b-41d4-a716-446655440001 scopes: - datasets:read - models:read ttl_seconds: 3600 conditions: max_invocations: 100 responses: '201': description: Delegation offered content: application/json: schema: $ref: '#/components/schemas/MaipDelegation' '400': description: Validation error or scope escalation content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/delegations/cross-tenant/accept: post: operationId: maip.delegations.accept summary: Accept Delegation description: 'Accepts a pending delegation offer. The accepting agent must match the to_agent_id specified in the offer and provide the delegation token. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: delegationId in: path required: true schema: type: string format: uuid description: Delegation identifier requestBody: required: true content: application/json: schema: type: object required: - agent_id - token properties: agent_id: type: string format: uuid description: Accepting agent (must match to_agent_id) token: type: string description: Delegation acceptance token from the offer responses: '200': description: Delegation accepted content: application/json: schema: $ref: '#/components/schemas/MaipDelegation' '400': description: Validation error or token mismatch content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Delegation not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/events: post: operationId: maip.observability.events.emit summary: Emit Event description: 'Emits a structured observability event into the MAIP event stream for auditing, alerting, and operational monitoring. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - event_type properties: event_type: type: string description: Dot-separated event type identifier (e.g. agent.registered, orchestration.completed) agent_id: type: string description: MAIP agent identifier associated with the event resource_id: type: string description: Identifier of the resource affected by the event metadata: type: object additionalProperties: true description: Arbitrary key-value metadata providing additional context severity: type: string enum: - info - warn - error default: info description: Event severity level responses: '201': description: Event emitted successfully content: application/json: schema: type: object properties: id: type: string description: Unique event identifier (maip-evt:ULID) event_type: type: string agent_id: type: string resource_id: type: string severity: type: string created_at: type: string format: date-time '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' get: operationId: maip.observability.events.list summary: List Observability Events description: 'Returns a paginated, time-ordered list of observability events. Use this endpoint for debugging agent behavior and auditing activity. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: agent_id in: query schema: type: string format: uuid description: Filter by agent - name: event_type in: query schema: type: string description: Filter by event type - name: from in: query schema: type: string format: date-time description: Start of time range (ISO 8601) - name: to in: query schema: type: string format: date-time description: End of time range (ISO 8601) - name: limit in: query schema: type: integer default: 50 minimum: 1 maximum: 500 - name: offset in: query schema: type: integer default: 0 minimum: 0 responses: '200': description: Paginated observability events content: application/json: schema: $ref: '#/components/schemas/MaipObservabilityEventList' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/metrics: get: operationId: maip.observability.metrics.get summary: Get Observability Metrics description: 'Returns time-series metrics for agent activity. Supports multiple metric names and configurable time intervals for aggregation. ' tags: - Machine Identity security: - APIKey: [] parameters: - name: agent_id in: query schema: type: string format: uuid description: Filter by agent - name: metric_names in: query schema: type: string description: Comma-separated metric names (e.g. invocations,errors,latency_p99) - name: from in: query schema: type: string format: date-time description: Start of time range (ISO 8601) - name: to in: query schema: type: string format: date-time description: End of time range (ISO 8601) - name: interval in: query schema: type: string enum: - 1m - 5m - 15m - 1h - 6h - 1d default: 1h description: Aggregation interval responses: '200': description: Metrics data content: application/json: schema: $ref: '#/components/schemas/MaipMetrics' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/maip/policies: get: operationId: maip.policies.list summary: List MAIP Policies description: 'Returns all MAIP agent enforcement policies configured for the authenticated tenant. Only active policies are evaluated during runtime policy checks. ' tags: - Machine Identity security: - APIKey: [] responses: '200': description: Array of policies content: application/json: schema: type: array items: $ref: '#/components/schemas/MaipPolicy' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' post: operationId: maip.policies.create summary: Create MAIP Policy description: 'Creates a new MAIP agent enforcement policy. Policies define runtime rules evaluated when agents request access to scoped resources. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - name - rules properties: name: type: string maxLength: 256 description: Human-readable policy name description: type: string maxLength: 2048 description: Detailed description of the policy category: type: string enum: - scope - trust - rate - custom default: custom description: Policy category priority: type: integer minimum: 1 maximum: 1000 default: 100 description: Evaluation priority (lower = first) rules: type: array items: $ref: '#/components/schemas/MaipPolicyRule' description: Array of policy rules responses: '201': description: Policy created content: application/json: schema: $ref: '#/components/schemas/MaipPolicy' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/maip/policies/evaluate: post: operationId: maip.policies.evaluate summary: Evaluate MAIP Policy description: 'Evaluates all active MAIP policies against a specific agent and requested scope. Uses deny-overrides model: any matching deny rule blocks the action. ' tags: - Machine Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - agent_id - scope properties: agent_id: type: string description: MAIP-compliant agent identifier scope: type: string description: Permission scope being requested action: type: string description: Specific action being performed resource: type: string description: Specific resource being accessed responses: '200': description: Evaluation result content: application/json: schema: $ref: '#/components/schemas/MaipPolicyEvaluateResponse' '400': description: Missing required fields content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/config: get: operationId: billing.config summary: Get billing configuration description: Returns the effective payment provider and current plan for the authenticated tenant. tags: - Billing security: - APIKey: [] parameters: - name: country in: query schema: type: string description: ISO 3166-1 alpha-2 country code for provider routing override responses: '200': description: Billing configuration content: application/json: schema: type: object properties: country_code: type: string effective_provider: type: string visible_providers: type: array items: type: string current_plan: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/status: get: operationId: billing.status summary: Get billing status description: Returns the billing status, current plan, and feature flags for the authenticated tenant. tags: - Billing security: - APIKey: [] responses: '200': description: Billing status content: application/json: schema: type: object properties: plan: type: string status: type: string trial_ends_at: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/entitlements: get: operationId: billing.entitlements summary: Get billing entitlements description: Returns all entitlements (feature limits and quotas) for the authenticated tenant's plan. tags: - Billing security: - APIKey: [] responses: '200': description: Entitlements list content: application/json: schema: type: object properties: plan: type: string entitlements: type: object additionalProperties: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/usage: get: operationId: billing.usage summary: Get billing usage description: Returns metered usage for the current billing period. tags: - Billing security: - APIKey: [] parameters: - name: period in: query schema: type: string description: Billing period (e.g. "2026-04") responses: '200': description: Usage data content: application/json: schema: type: object properties: period: type: string usage: type: object additionalProperties: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/plans: get: operationId: billing.plans summary: List billing plans description: Returns all available billing plans with pricing, features, and entitlements. tags: - Billing security: - APIKey: [] responses: '200': description: Plans list content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string name: type: string price: type: number currency: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/rates: get: operationId: billing.rates summary: Get billing rates description: Returns per-unit metered rates for the authenticated tenant's plan. tags: - Billing security: - APIKey: [] responses: '200': description: Rates content: application/json: schema: type: object properties: rates: type: object additionalProperties: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/subscription: get: operationId: billing.subscription summary: Get subscription details description: Returns the active subscription details including plan, status, and renewal date. tags: - Billing security: - APIKey: [] responses: '200': description: Subscription details content: application/json: schema: type: object properties: id: type: string plan: type: string status: type: string current_period_end: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/invoices: get: operationId: billing.invoices summary: List invoices description: Returns a paginated list of invoices for the authenticated tenant. tags: - Billing security: - APIKey: [] parameters: - name: limit in: query schema: type: integer default: 20 description: Maximum number of invoices to return - name: cursor in: query schema: type: string description: Pagination cursor responses: '200': description: Invoice list content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string amount: type: number currency: type: string status: type: string created_at: type: string cursor: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/estimate: post: operationId: billing.estimate summary: Estimate billing description: Returns a cost estimate for a plan change or addon without executing it. tags: - Billing security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - plan properties: plan: type: string description: Target plan identifier addons: type: array items: type: string description: Optional addon identifiers responses: '200': description: Cost estimate content: application/json: schema: type: object properties: subtotal: type: number tax: type: number total: type: number currency: type: string proration: type: number '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/projected-invoice: post: operationId: billing.projectedInvoice summary: Project next invoice description: Returns a projected invoice for the next billing cycle based on current usage trends. tags: - Billing security: - APIKey: [] requestBody: content: application/json: schema: type: object properties: plan: type: string description: Optional plan override for projection responses: '200': description: Projected invoice content: application/json: schema: type: object properties: projected_total: type: number currency: type: string period_start: type: string period_end: type: string line_items: type: array items: type: object '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/checkout: post: operationId: billing.checkout summary: Create checkout session description: Creates a hosted checkout session for plan upgrade or subscription creation. tags: - Billing security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - plan properties: plan: type: string description: Plan identifier to subscribe to success_url: type: string description: URL to redirect after successful checkout cancel_url: type: string description: URL to redirect on checkout cancellation responses: '200': description: Checkout session content: application/json: schema: type: object properties: checkout_url: type: string session_id: type: string expires_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/cancel: post: operationId: billing.cancel summary: Cancel subscription description: Cancels the active subscription at the end of the current billing period. tags: - Billing security: - APIKey: [] requestBody: content: application/json: schema: type: object properties: reason: type: string description: Optional cancellation reason immediate: type: boolean description: If true, cancel immediately instead of at period end responses: '200': description: Cancellation confirmed content: application/json: schema: type: object properties: status: type: string cancels_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/portal: post: operationId: billing.portal summary: Create billing portal session description: Creates a hosted billing portal session for managing payment methods, invoices, and subscription. tags: - Billing security: - APIKey: [] requestBody: content: application/json: schema: type: object properties: return_url: type: string description: URL to redirect after portal session responses: '200': description: Portal session content: application/json: schema: type: object properties: portal_url: type: string expires_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/addons/attach: post: operationId: billing.addons.attach summary: Attach addon description: Attaches a billing addon to the tenant's subscription. tags: - Billing security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - addon_id properties: addon_id: type: string description: Addon identifier to attach quantity: type: integer description: Number of addon units responses: '200': description: Addon attached content: application/json: schema: type: object properties: addon_id: type: string status: type: string effective_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipts: get: operationId: receipts.list summary: List receipts description: Returns a paginated list of receipts for the authenticated tenant. tags: - Receipts security: - APIKey: [] parameters: - name: limit in: query schema: type: integer default: 20 description: Maximum number of receipts to return - name: cursor in: query schema: type: string description: Pagination cursor - name: receipt_type in: query schema: type: string description: Filter by receipt type - name: status in: query schema: type: string enum: - active - revoked - redacted description: Filter by status responses: '200': description: Receipt list content: application/json: schema: type: object properties: items: type: array items: type: object properties: receipt_id: type: string receipt_type: type: string status: type: string subject: type: string issued_at: type: string cursor: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' post: operationId: receipts.mint summary: Mint receipt description: Creates a cryptographically signed, transparency-log-anchored receipt event. tags: - Receipts security: - APIKey: [] parameters: - name: Idempotency-Key in: header required: true schema: type: string description: UUID for idempotent minting requestBody: required: true content: application/json: schema: type: object required: - issuer_id - kid - alg - receipt_type - subject - payload properties: issuer_id: type: string description: UUID of the issuer signing the receipt kid: type: string description: Key ID of the signing key alg: $ref: '#/components/schemas/SigningAlgorithm' description: Signing algorithm receipt_type: type: string description: Receipt type name subject: type: string description: Subject identifier payload: type: object description: Receipt payload validated against schema metadata: type: object description: Optional metadata responses: '201': description: Receipt created content: application/json: schema: type: object properties: receipt_id: type: string receipt_type: type: string status: type: string issuer_id: type: string subject: type: string signature: type: object properties: alg: type: string kid: type: string value: type: string issued_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Schema validation error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipts/{id}: get: operationId: receipts.get summary: Get receipt description: Retrieves a single receipt by ID. tags: - Receipts security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string description: Receipt UUID responses: '200': description: Receipt details content: application/json: schema: type: object properties: receipt_id: type: string receipt_type: type: string status: type: string subject: type: string payload: type: object signature: type: object issued_at: type: string '404': description: Receipt not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipts/{id}/revoke: post: operationId: receipts.revoke summary: Revoke receipt description: Revokes a receipt, marking it as invalid. The revocation is anchored in the transparency log. tags: - Receipts security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string description: Receipt UUID requestBody: required: true content: application/json: schema: type: object required: - reason properties: reason: type: string description: Revocation reason responses: '200': description: Receipt revoked content: application/json: schema: type: object properties: receipt_id: type: string status: type: string revoked_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipts/{id}/redact: post: operationId: receipts.redact summary: Redact receipt description: Redacts sensitive fields from a receipt while preserving the cryptographic proof chain. tags: - Receipts security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string description: Receipt UUID requestBody: required: true content: application/json: schema: type: object required: - fields properties: fields: type: array items: type: string description: JSON paths of fields to redact reason: type: string description: Redaction reason responses: '200': description: Receipt redacted content: application/json: schema: type: object properties: receipt_id: type: string status: type: string redacted_fields: type: array items: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipts/search: post: operationId: receipts.search summary: Search receipts description: Search receipts by subject, type, date range, or custom metadata filters. tags: - Receipts security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object properties: subject: type: string receipt_type: type: string status: type: string from: type: string description: ISO 8601 start date to: type: string description: ISO 8601 end date limit: type: integer default: 20 responses: '200': description: Search results content: application/json: schema: type: object properties: items: type: array items: type: object total: type: integer '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipts/verify: post: operationId: receipts.verify summary: Verify receipt description: Verifies a receipt's cryptographic signature and transparency log inclusion. tags: - Receipts security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - receipt_id properties: receipt_id: type: string description: Receipt UUID to verify responses: '200': description: Verification result content: application/json: schema: type: object properties: valid: type: boolean receipt_id: type: string checks: type: object '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipts/export: post: operationId: receipts.export summary: Export receipts description: Exports receipts matching the given filters as a downloadable archive. tags: - Receipts security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object properties: receipt_type: type: string from: type: string to: type: string format: type: string enum: - json - csv default: json responses: '202': description: Export initiated content: application/json: schema: type: object properties: export_id: type: string status: type: string download_url: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipts/{id}/proof-bundle: get: operationId: receipts.proofBundle summary: Get receipt proof bundle description: Returns the full cryptographic proof bundle for a receipt including transparency log inclusion proof. tags: - Receipts security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string description: Receipt UUID responses: '200': description: Proof bundle content: application/json: schema: type: object properties: receipt_id: type: string signature: type: object transparency_proof: type: object issuer: type: object '404': description: Receipt not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipt-types: get: operationId: receiptTypes.list summary: List receipt types description: Returns all registered receipt types for the authenticated tenant. tags: - Receipts security: - APIKey: [] responses: '200': description: Receipt types list content: application/json: schema: type: object properties: items: type: array items: type: object properties: name: type: string display_name: type: string schema: type: object created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' post: operationId: receiptTypes.create summary: Create receipt type description: Registers a custom receipt type with a JSON Schema for payload validation. tags: - Receipts security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - name - display_name - schema properties: name: type: string description: Machine-readable receipt type name display_name: type: string description: Human-readable name description: type: string schema: type: object description: JSON Schema for payload validation responses: '201': description: Receipt type created content: application/json: schema: type: object properties: name: type: string display_name: type: string schema: type: object created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipt-types/{name}: get: operationId: receiptTypes.get summary: Get receipt type description: Retrieves a single receipt type by name. tags: - Receipts security: - APIKey: [] parameters: - name: name in: path required: true schema: type: string description: Receipt type name responses: '200': description: Receipt type details content: application/json: schema: type: object properties: name: type: string display_name: type: string schema: type: object signing_policy: type: object nullable: true '404': description: Receipt type not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/receipt-types/{name}/signing-policy: post: operationId: receiptTypes.signingPolicy summary: Set signing policy description: Sets the signing policy for a receipt type, controlling which algorithms and keys are allowed. tags: - Receipts security: - APIKey: [] parameters: - name: name in: path required: true schema: type: string description: Receipt type name requestBody: required: true content: application/json: schema: type: object required: - allowed_algorithms properties: allowed_algorithms: type: array items: type: string description: List of allowed signing algorithms require_hsm: type: boolean description: Require HSM-backed keys responses: '200': description: Signing policy updated content: application/json: schema: type: object properties: name: type: string signing_policy: type: object '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/evaluate: post: operationId: risk.evaluate summary: Risk evaluate description: Unified risk evaluation. Ingests a signal, evaluates against policies, creates a signed risk decision. tags: - Risk security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - signal_type - subject_id - risk_score properties: signal_type: type: string enum: - velocity - ato - deepfake - impersonation - geo_anomaly - behavior - device_fingerprint subject_id: type: string risk_score: type: integer minimum: 0 maximum: 100 subject_type: type: string default: user mint_receipt: type: boolean issuer_id: type: string kid: type: string responses: '200': description: Risk decision content: application/json: schema: type: object properties: decision_id: type: string signal_id: type: string decision: type: string enum: - allow - challenge - block - review policy_id: type: string nullable: true receipt_id: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/ato/evaluate: post: operationId: risk.ato.evaluate summary: ATO risk evaluate description: Evaluates account takeover risk for a subject using behavioral signals and device fingerprints. tags: - Risk security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - subject_id properties: subject_id: type: string ip_address: type: string user_agent: type: string device_fingerprint: type: string action: type: string responses: '200': description: ATO evaluation result content: application/json: schema: type: object properties: risk_score: type: integer decision: type: string signals: type: array items: type: object '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/ato/profile/{subject_id}: get: operationId: risk.ato.profile summary: Get ATO profile description: Returns the account takeover risk profile for a subject including historical signals. tags: - Risk security: - APIKey: [] parameters: - name: subject_id in: path required: true schema: type: string description: Subject identifier responses: '200': description: ATO profile content: application/json: schema: type: object properties: subject_id: type: string risk_level: type: string last_login: type: string known_devices: type: integer alerts: type: array items: type: object '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/ato/alerts: get: operationId: risk.ato.alerts summary: List ATO alerts description: Returns account takeover alerts for the authenticated tenant. tags: - Risk security: - APIKey: [] parameters: - name: limit in: query schema: type: integer default: 20 - name: severity in: query schema: type: string enum: - low - medium - high - critical responses: '200': description: ATO alerts content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string subject_id: type: string severity: type: string created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/deepfake/scan: post: operationId: risk.deepfake.scan summary: Deepfake scan description: Submits media for deepfake detection analysis. tags: - Risk security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - subject_ref - media_url properties: subject_ref: type: string description: Reference identifier for the subject media_url: type: string description: URL of the media to scan media_type: type: string enum: - image - video - audio callback_url: type: string description: Webhook URL for async results responses: '202': description: Scan initiated content: application/json: schema: type: object properties: scan_id: type: string status: type: string subject_ref: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/deepfake/results/{subject_ref}: get: operationId: risk.deepfake.results summary: Get deepfake results description: Returns deepfake scan results for a subject reference. tags: - Risk security: - APIKey: [] parameters: - name: subject_ref in: path required: true schema: type: string description: Subject reference from the scan request responses: '200': description: Scan results content: application/json: schema: type: object properties: subject_ref: type: string verdict: type: string enum: - authentic - deepfake - inconclusive confidence: type: number scans: type: array items: type: object '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/events: post: operationId: risk.normalizeEvent summary: Normalize risk event description: Ingests and normalizes a risk event into the risk signal pipeline. tags: - Risk security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - event_type - subject_id properties: event_type: type: string subject_id: type: string data: type: object timestamp: type: string responses: '201': description: Event ingested content: application/json: schema: type: object properties: event_id: type: string signal_id: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/velocity/record: post: operationId: risk.velocity.record summary: Record velocity event description: Records a velocity event for rate-limit and anomaly detection. tags: - Risk security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - subject_id - action properties: subject_id: type: string action: type: string description: Action type being tracked metadata: type: object responses: '201': description: Velocity event recorded content: application/json: schema: type: object properties: event_id: type: string current_count: type: integer window: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/velocity/{subject_id}: get: operationId: risk.velocity.windows summary: Get velocity windows description: Returns velocity counts across time windows for a subject. tags: - Risk security: - APIKey: [] parameters: - name: subject_id in: path required: true schema: type: string description: Subject identifier - name: action in: query schema: type: string description: Filter by action type responses: '200': description: Velocity windows content: application/json: schema: type: object properties: subject_id: type: string windows: type: array items: type: object properties: window: type: string count: type: integer action: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/velocity: get: operationId: risk.velocity.anomalies summary: List velocity anomalies description: Returns detected velocity anomalies across all subjects. tags: - Risk security: - APIKey: [] parameters: - name: limit in: query schema: type: integer default: 20 - name: severity in: query schema: type: string responses: '200': description: Velocity anomalies content: application/json: schema: type: object properties: items: type: array items: type: object properties: subject_id: type: string action: type: string count: type: integer threshold: type: integer severity: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/webhooks/endpoints: get: operationId: webhooks.endpoints.list summary: List webhook endpoints description: Returns all configured webhook endpoints for the authenticated tenant. tags: - Webhooks security: - APIKey: [] responses: '200': description: Webhook endpoints content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string name: type: string url: type: string status: type: string event_filters: type: array items: type: string created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' post: operationId: webhooks.endpoints.create summary: Create webhook endpoint description: Registers a new webhook endpoint for the authenticated tenant. tags: - Webhooks security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - name - url - event_filters properties: name: type: string description: Human-readable endpoint name url: type: string description: HTTPS URL for webhook deliveries event_filters: type: array items: type: string description: Event types or wildcard patterns responses: '201': description: Endpoint created content: application/json: schema: type: object properties: id: type: string name: type: string url: type: string status: type: string secret: type: string event_filters: type: array items: type: string created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '402': description: Plan limit reached content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/webhooks/endpoints/{id}/rotate: post: operationId: webhooks.endpoints.rotateSecret summary: Rotate webhook secret description: Generates a new signing secret for the webhook endpoint. The old secret is immediately invalidated. tags: - Webhooks security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string description: Webhook endpoint ID responses: '200': description: Secret rotated content: application/json: schema: type: object properties: id: type: string secret: type: string rotated_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' requestBody: *id001 /v1/webhooks/endpoints/{id}/deliveries: get: operationId: webhooks.endpoints.deliveries summary: List webhook deliveries description: Returns delivery history for a webhook endpoint. tags: - Webhooks security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string description: Webhook endpoint ID - name: limit in: query schema: type: integer default: 20 responses: '200': description: Delivery history content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string event_type: type: string status_code: type: integer delivered_at: type: string success: type: boolean '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/webhooks/test-delivery: post: operationId: webhooks.testDelivery summary: Test webhook delivery description: Sends a test event to a webhook endpoint to verify connectivity. tags: - Webhooks security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - endpoint_id properties: endpoint_id: type: string description: Webhook endpoint ID to test event_type: type: string description: Event type to simulate default: test.ping responses: '200': description: Test delivery result content: application/json: schema: type: object properties: success: type: boolean status_code: type: integer response_time_ms: type: integer '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/audit/retention: get: operationId: audit.retention.get summary: Get retention policy description: Returns the audit log retention policy for the authenticated tenant. tags: - Audit security: - APIKey: [] parameters: - name: environment_id in: query schema: type: string description: Optional environment filter responses: '200': description: Retention policy content: application/json: schema: type: object properties: retention_days: type: integer hard_delete: type: boolean export_allowed: type: boolean environment_id: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' put: operationId: audit.retention.update summary: Update retention policy description: Updates the audit log retention policy for the authenticated tenant. tags: - Audit security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - retention_days properties: retention_days: type: integer description: Number of days to retain audit logs hard_delete: type: boolean description: Whether to permanently delete logs after retention period export_allowed: type: boolean environment_id: type: string responses: '200': description: Retention policy updated content: application/json: schema: type: object properties: retention_days: type: integer hard_delete: type: boolean updated_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/siem/export: post: operationId: audit.siem.create summary: Create SIEM integration description: Creates a new SIEM integration for forwarding audit logs. tags: - Audit security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - type - endpoint properties: type: type: string enum: - splunk - datadog - elastic - sentinel - custom description: SIEM provider type endpoint: type: string description: SIEM endpoint URL api_key: type: string description: Authentication key for the SIEM endpoint event_filters: type: array items: type: string description: Event types to forward responses: '201': description: SIEM integration created content: application/json: schema: type: object properties: id: type: string type: type: string endpoint: type: string status: type: string created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/siem/export/{id}: get: operationId: audit.siem.get summary: Get SIEM export description: Returns a previously created SIEM export by ID. tags: - Audit security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string description: SIEM integration ID requestBody: required: true content: application/json: schema: type: object properties: endpoint: type: string api_key: type: string event_filters: type: array items: type: string status: type: string enum: - active - paused responses: '200': description: SIEM integration updated content: application/json: schema: type: object properties: id: type: string status: type: string updated_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' delete: operationId: audit.siem.delete summary: Delete SIEM integration description: Deletes a SIEM integration. Log forwarding stops immediately. tags: - Audit security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string description: SIEM integration ID responses: '204': description: SIEM integration deleted '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/block: post: operationId: risk.block summary: Block a subject description: Immediately blocks a subject from further activity based on risk assessment. tags: - Risk Enforcement security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - subject_id - reason properties: subject_id: type: string description: Subject identifier to block reason: type: string description: Reason for blocking duration_seconds: type: integer description: Optional block duration in seconds (omit for permanent) metadata: type: object description: Additional context for the block action responses: '200': description: Subject blocked content: application/json: schema: type: object properties: block_id: type: string subject_id: type: string status: type: string blocked_at: type: string expires_at: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/challenge: post: operationId: risk.challenge summary: Challenge a subject description: Issues a verification challenge to a subject requiring additional proof of identity. tags: - Risk Enforcement security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - subject_id - challenge_type properties: subject_id: type: string description: Subject identifier to challenge challenge_type: type: string enum: - mfa - captcha - email_verify - phone_verify - document description: Type of challenge to issue reason: type: string description: Reason for the challenge ttl_seconds: type: integer description: Time-to-live for the challenge in seconds responses: '200': description: Challenge issued content: application/json: schema: type: object properties: challenge_id: type: string subject_id: type: string challenge_type: type: string status: type: string expires_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/decisions: get: operationId: risk.decisions.list summary: List risk decisions description: Returns a paginated list of risk decisions for the authenticated tenant. tags: - Risk Enforcement security: - APIKey: [] parameters: - name: limit in: query schema: type: integer default: 20 description: Maximum number of decisions to return - name: cursor in: query schema: type: string description: Pagination cursor - name: subject_id in: query schema: type: string description: Filter by subject identifier - name: decision in: query schema: type: string enum: - allow - challenge - block - review description: Filter by decision outcome responses: '200': description: List of risk decisions content: application/json: schema: type: object properties: items: type: array items: type: object properties: decision_id: type: string subject_id: type: string decision: type: string risk_score: type: integer created_at: type: string cursor: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/quarantine/{subject_id}: get: operationId: risk.quarantine.get summary: Get quarantine status description: Returns the quarantine status for a subject including reason and expiry. tags: - Risk Enforcement security: - APIKey: [] parameters: - name: subject_id in: path required: true schema: type: string description: Subject identifier responses: '200': description: Quarantine status content: application/json: schema: type: object properties: subject_id: type: string quarantined: type: boolean reason: type: string nullable: true quarantined_at: type: string nullable: true expires_at: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' delete: operationId: risk.quarantine.remove summary: Remove from quarantine description: Removes a subject from quarantine, restoring normal access. tags: - Risk Enforcement security: - APIKey: [] parameters: - name: subject_id in: path required: true schema: type: string description: Subject identifier responses: '200': description: Subject removed from quarantine content: application/json: schema: type: object properties: subject_id: type: string status: type: string removed_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/config: get: operationId: risk.config.get summary: Get risk configuration description: Returns the current risk engine configuration including thresholds and policy rules. tags: - Risk Enforcement security: - APIKey: [] responses: '200': description: Risk configuration content: application/json: schema: type: object properties: block_threshold: type: integer description: Risk score threshold for automatic blocking challenge_threshold: type: integer description: Risk score threshold for issuing challenges quarantine_duration_seconds: type: integer description: Default quarantine duration enabled_policies: type: array items: type: string updated_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' put: operationId: risk.config.update summary: Update risk configuration description: Updates the risk engine configuration. Changes take effect immediately. tags: - Risk Enforcement security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object properties: block_threshold: type: integer description: Risk score threshold for automatic blocking (0-100) challenge_threshold: type: integer description: Risk score threshold for issuing challenges (0-100) quarantine_duration_seconds: type: integer description: Default quarantine duration in seconds enabled_policies: type: array items: type: string description: List of policy IDs to enable responses: '200': description: Risk configuration updated content: application/json: schema: type: object properties: block_threshold: type: integer challenge_threshold: type: integer quarantine_duration_seconds: type: integer enabled_policies: type: array items: type: string updated_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/dashboard/metrics: get: operationId: risk.dashboard.metrics summary: Dashboard metrics description: Returns aggregated risk metrics for the dashboard including totals and breakdowns by decision type. tags: - Risk Enforcement security: - APIKey: [] parameters: - name: period in: query schema: type: string enum: - 1h - 24h - 7d - 30d default: 24h description: Time period for metrics aggregation responses: '200': description: Risk dashboard metrics content: application/json: schema: type: object properties: total_evaluations: type: integer total_blocks: type: integer total_challenges: type: integer total_allows: type: integer avg_risk_score: type: number period: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/dashboard/trends: get: operationId: risk.dashboard.trends summary: Dashboard trends description: Returns time-series risk trend data for visualization in the dashboard. tags: - Risk Enforcement security: - APIKey: [] parameters: - name: period in: query schema: type: string enum: - 1h - 24h - 7d - 30d default: 7d description: Time period for trend data - name: granularity in: query schema: type: string enum: - 5m - 1h - 1d default: 1h description: Data point granularity responses: '200': description: Risk trend data content: application/json: schema: type: object properties: period: type: string granularity: type: string data_points: type: array items: type: object properties: timestamp: type: string evaluations: type: integer blocks: type: integer challenges: type: integer avg_score: type: number '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/risk/dashboard/top-subjects: get: operationId: risk.dashboard.topSubjects summary: Top risk subjects description: Returns the top subjects by risk score or event count for the dashboard. tags: - Risk Enforcement security: - APIKey: [] parameters: - name: limit in: query schema: type: integer default: 10 description: Number of top subjects to return - name: sort_by in: query schema: type: string enum: - risk_score - event_count - last_seen default: risk_score description: Sort criteria - name: period in: query schema: type: string enum: - 24h - 7d - 30d default: 7d description: Time period to consider responses: '200': description: Top risk subjects content: application/json: schema: type: object properties: items: type: array items: type: object properties: subject_id: type: string risk_score: type: integer event_count: type: integer last_decision: type: string last_seen: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/billing/addons/detach: post: operationId: billing.addons.detach summary: Detach addon description: Detaches a billing addon from the tenant's subscription. tags: - Billing security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - addon_id properties: addon_id: type: string description: Addon identifier to detach responses: '200': description: Addon detached content: application/json: schema: type: object properties: addon_id: type: string status: type: string detached_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/consumer/me: get: operationId: consumer.profile summary: Get consumer profile description: Returns the authenticated consumer's profile including name, email, MFA status, roles. tags: - Consumer security: - APIKey: [] responses: '200': description: Consumer profile content: application/json: schema: type: object properties: id: type: string tenant_id: type: string email: type: string name: type: string username: type: string mfa_enabled: type: boolean roles: type: array items: type: string permissions: type: array items: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/consumer/similarity: get: operationId: consumer.similarity summary: Get similarity score description: Returns content similarity scores for the authenticated consumer's portfolio. tags: - Consumer security: - APIKey: [] responses: '200': description: Similarity scores content: application/json: schema: type: object properties: scores: type: array items: type: object properties: attestation_id: type: string similarity: type: number match_type: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/consumer/protections/{id}/visibility: put: operationId: consumer.updateVisibility summary: Update protection visibility description: Updates the visibility setting of a protection in the consumer's portfolio. tags: - Consumer security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string description: Protection ID requestBody: required: true content: application/json: schema: type: object required: - visibility properties: visibility: type: string enum: - public - private - unlisted description: Visibility level responses: '200': description: Visibility updated content: application/json: schema: type: object properties: id: type: string visibility: type: string updated_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/platform/blog/posts: get: operationId: blog.list summary: List blog posts description: Returns a paginated list of blog posts. tags: - Platform security: - APIKey: [] parameters: - name: status in: query schema: type: string enum: - draft - published - archived - name: category in: query schema: type: string - name: limit in: query schema: type: integer default: 20 responses: '200': description: Blog posts content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string title: type: string slug: type: string category: type: string status: type: string published_at: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' post: operationId: blog.create summary: Create blog post description: Creates a new blog post as draft or published. tags: - Platform security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - title - slug - category - content properties: title: type: string slug: type: string category: type: string enum: - engineering - product - security - company - industry content: type: string description: Post body in Markdown status: type: string enum: - draft - published default: draft excerpt: type: string cover_image_url: type: string tags: type: array items: type: string responses: '201': description: Post created content: application/json: schema: type: object properties: id: type: string title: type: string slug: type: string status: type: string created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/platform/blog/posts/{id}: get: operationId: blog.get summary: Get blog post description: Retrieves a blog post by ID. tags: - Platform security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Blog post content: application/json: schema: type: object properties: id: type: string title: type: string slug: type: string category: type: string content: type: string status: type: string tags: type: array items: type: string created_at: type: string '404': description: Post not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' put: operationId: blog.update summary: Update blog post description: Updates an existing blog post. tags: - Platform security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: title: type: string slug: type: string category: type: string content: type: string excerpt: type: string cover_image_url: type: string tags: type: array items: type: string responses: '200': description: Post updated content: application/json: schema: type: object properties: id: type: string status: type: string updated_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' delete: operationId: blog.delete summary: Delete blog post description: Permanently deletes a blog post. tags: - Platform security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string responses: '204': description: Post deleted '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/platform/blog/posts/{id}/publish: post: operationId: blog.publish summary: Publish blog post description: Publishes a draft blog post, making it publicly visible. tags: - Platform security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Post published content: application/json: schema: type: object properties: id: type: string status: type: string published_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' requestBody: *id001 /v1/platform/blog/posts/{id}/archive: post: operationId: blog.archive summary: Archive blog post description: Archives a blog post, removing it from public view. tags: - Platform security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Post archived content: application/json: schema: type: object properties: id: type: string status: type: string archived_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' requestBody: *id001 /v1/platform/leads: post: operationId: platform.leads.create summary: Create lead description: Captures a sales lead from the website contact form. tags: - Platform security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - email - name properties: email: type: string name: type: string company: type: string message: type: string source: type: string responses: '201': description: Lead captured content: application/json: schema: type: object properties: id: type: string status: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/issuer-applications: get: operationId: issuerApplications.list summary: List issuer applications description: Returns all issuer applications for the authenticated tenant. tags: - Trust Registry security: - APIKey: [] parameters: - name: status in: query schema: type: string enum: - DRAFT - SUBMITTED - APPROVED - REJECTED responses: '200': description: Applications list content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string legal_name: type: string status: type: string created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' post: operationId: issuerApplications.create summary: Create issuer application description: Creates a new issuer application in draft status. tags: - Trust Registry security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - legal_name properties: legal_name: type: string display_name: type: string jurisdiction: type: string registration_ref: type: string requested_trust_tier: type: string enum: - verified_org - government_entity - accredited_institution contact_name: type: string contact_email: type: string org_id: type: string responses: '201': description: Application created content: application/json: schema: type: object properties: id: type: string legal_name: type: string status: type: string created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/issuer-applications/{id}: get: operationId: issuerApplications.get summary: Get issuer application description: Retrieves an issuer application by ID. tags: - Trust Registry security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Application details content: application/json: schema: type: object properties: id: type: string legal_name: type: string display_name: type: string jurisdiction: type: string status: type: string created_at: type: string '404': description: Application not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/issuer-applications/{id}/submit: post: operationId: issuerApplications.submit summary: Submit issuer application description: Submits a draft issuer application for review. tags: - Trust Registry security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Application submitted content: application/json: schema: type: object properties: id: type: string status: type: string submitted_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' requestBody: *id001 /v1/policies: get: operationId: policies.list summary: List policies description: Returns all issuance policies for the authenticated tenant. tags: - Policies security: - APIKey: [] parameters: - name: category in: query schema: type: string enum: - MINT - VERIFY - BUNDLE_EXPORT - name: status in: query schema: type: string enum: - DRAFT - ACTIVE - DISABLED responses: '200': description: Policies list content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string name: type: string category: type: string status: type: string version: type: integer '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' post: operationId: policies.create summary: Create policy description: Creates a new issuance policy with rules for minting, verification, or proof-bundle export. tags: - Policies security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - name - category - status - rules properties: name: type: string category: type: string enum: - MINT - VERIFY - BUNDLE_EXPORT status: type: string enum: - DRAFT - ACTIVE - DISABLED description: type: string language: type: string default: json_rules rules: type: object description: Rule set with rules array and default_effect properties: rules: type: array items: type: object properties: id: type: string description: type: string conditions: type: array items: type: object effect: type: string enum: - ALLOW - DENY default_effect: type: string enum: - ALLOW - DENY responses: '201': description: Policy created content: application/json: schema: type: object properties: id: type: string name: type: string category: type: string status: type: string version: type: integer created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/policies/evaluate: post: operationId: policies.evaluate summary: Evaluate policies description: Evaluates all active policies against a specific action and context. tags: - Policies security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - category - context properties: category: type: string enum: - MINT - VERIFY - BUNDLE_EXPORT context: type: object description: Evaluation context (e.g. issuer details, attestation metadata) responses: '200': description: Evaluation result content: application/json: schema: type: object properties: decision: type: string enum: - ALLOW - DENY matched_policy: type: string nullable: true matched_rule: type: string nullable: true reason: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/policies/{id}: delete: operationId: policies.delete summary: Delete policy description: Deletes an issuance policy. Active policies must be disabled first. tags: - Policies security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string responses: '204': description: Policy deleted '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/announcements: get: operationId: announcements.list summary: List announcements description: Returns platform announcements for the authenticated tenant. tags: - Platform security: - APIKey: [] responses: '200': description: Announcements content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string subject: type: string body: type: string priority: type: string enum: - NORMAL - URGENT - CRITICAL is_read: type: boolean created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /v1/announcements/{id}/read: post: operationId: announcements.markRead summary: Mark announcement read description: Marks an announcement as read for the authenticated tenant. tags: - Platform security: - APIKey: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Marked as read content: application/json: schema: type: object properties: id: type: string is_read: type: boolean '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' requestBody: *id001 /v1/assets/upload: post: operationId: assets.upload summary: Upload asset description: Uploads a file to the asset store for use with issuers, evidence, and branding. tags: - Assets security: - APIKey: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: File to upload (max 5 MB) purpose: type: string description: Asset purpose tag responses: '201': description: Asset uploaded content: application/json: schema: type: object properties: id: type: string url: type: string content_type: type: string size: type: integer purpose: type: string created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' /health/status: get: operationId: health.status summary: Programmatic status description: Returns real-time service health for all Truthlocks services. No authentication required. tags: - Health responses: '200': description: Service health content: application/json: schema: type: object properties: status: type: string enum: - operational - degraded - outage timestamp: type: string services: type: array items: type: object properties: id: type: string name: type: string status: type: string responseTime: type: integer nullable: true /v1/role-bindings: post: operationId: identity.assignRole summary: Assign role description: Creates a role binding, assigning a role to a user or service account. tags: - Identity security: - APIKey: [] requestBody: required: true content: application/json: schema: type: object required: - role_id - principal_id properties: role_id: type: string description: Role identifier to assign principal_id: type: string description: User or service account identifier principal_type: type: string enum: - user - service_account default: user scope: type: string description: Optional scope restriction responses: '201': description: Role binding created content: application/json: schema: type: object properties: id: type: string role_id: type: string principal_id: type: string created_at: type: string '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - APIKey: []