# API reference Canonical HTML: https://spoolis.com/docs/api. This page is also available in machine-readable Markdown. Reference for the implemented bearer-authenticated v1 Spool routes and production API keys. ## Authentication Create an spk_live_ production key on the signed-in API keys page at `/dashboard/api-keys`. The full key is shown once. Store it securely and send it as `Authorization: Bearer spk_live_`. Missing, unknown, or revoked keys return 401. Anyone can review a shared Spool, but production acceptance requires authenticated access. ## Resources POST /api/v1/spools creates a Spool. GET /api/v1/spools/{id} reads it. GET /api/v1/spools/{id}/events reads its event array. ## Endpoint index The HTML API page renders method, path, auth, environment, purpose, and guide directly from openApiDocument.paths. Use /openapi.json for schemas. The index covers key exchange, Spool create/read/invite/events/actions, receipt status, attestation verification, sandbox session state/minting, sandbox compile, and sandbox actions. ## Verification method request values deterministic is Live, human_confirmed is Live, external_tool is Reserved, and ai_assisted is Planned. Schema acceptance does not mean an executor is live. Choose values using the single [method-status table](/docs/verification). ## Outcome Receipt In the canonical example, a buyer pays for 100 enrichment records at $1.00 per accepted record. Spoolis accepts 98, rejects 2 with reasons, and signs an Outcome Receipt for $98.00 earned. Verify it with @spoolis/receipt-verifier, optionally call GET /api/receipts/{id}/status, then let the payment stack act on earned under its own policy. Offline signature verification remains sufficient. ## Verify the underlying attestation POST /api/v1/attestations/verify accepts the complete lower-level signed attestation without authentication. It returns valid, environment, and machine-readable reasons without returning the submitted artifact. ## Settlement Spoolis determines earned value and signs the Outcome Receipt. A wallet, marketplace, payment system, or configured integration may verify and consume it, then act under its own authorization and settlement policy. The optional built-in path uses a configured settlement adapter. ## Actions POST /api/v1/spools/{id}/{action} supports propose, accept, decline, cancel, abandon, commit, evidence, verify, complete, and onboard-provider. Either party can abandon an active Spool before settlement is committed. Abandon requires a full-scope key. Lifecycle rules still determine whether an action is allowed. ## Troubleshooting by stage Session: session_expired, limit_reached, sandbox_resting, rate_limited, configuration_unavailable. Compile: invalid_json, input_too_large, ambiguity_required, validation_failed, compile_failed. Lifecycle: unauthenticated, forbidden, spool_not_found, unknown_action, invalid_state, store_conflict. Settlement: settlement_unavailable. Attestation: trusted_key_unavailable, internal_error. Receipt verifier: unknown_schema, environment_mismatch, invalid_evidence_root, invalid_run_digest, invalid_agreement_hash, receipt_id_mismatch, earned_exceeds_committed, earned_amount_mismatch, aggregation_inconsistent, untrusted_signing_key, signing_key_id_mismatch, invalid_signature, malformed_receipt, corrected, revoked. Advisories: status_source_unavailable, key_retiring. MCP: production_key_required, sandbox_session_failed. Branch on stable code or reason, not HTTP status alone. Follow retryable and remediation. Reject invalid receipts. Mint a fresh session for expired or exhausted sandbox sessions. Corrected or revoked requires consumer reconciliation and does not automatically reverse payment. ## Rate limits The configured v1 limit is 120 requests per minute per account or test party label and forwarded IP. When Upstash is absent, enforcement is not active.