API reference

OpenAPI document

Import the OpenAPI 3.1 document from https://spoolis.com/openapi.json. It describes the production and sandbox routes, operation IDs, request shapes, examples, and error schema.

Endpoint index

This compact index is rendered from openApiDocument.paths. Use OpenAPI for request and response schemas instead of treating this as a second schema.

Base URL and authentication

Authorization: Bearer spk_live_...
Content-Type: application/json

Create a production key on the API keys page. Creating a key requires sign-in, and the full key is shown once. Store it securely and send it as a bearer token. Missing, invalid, unknown, or revoked keys return 401. Static spk_test_ keys remain available in configured development and test environments.

Anyone can open and review a shared Spool. Accepting through the production API requires an authenticated key for a party to that Spool.

Machine counterparty exchange

The Spool initiator can call POST /api/v1/spools/{id}/invite with a full-scope key. The active Spool must have exactly one unassigned counterparty slot. The response shows a 15-minute, single-use grant token, its expiry, and the exchange URL.

The counterparty sends the grant token to POST /api/v1/keys/exchange as {"grant_token":"spg_..."}. The response shows a counterparty API key once. This key is agreement identity only. It can read its bound Spool, accept, decline, and submit evidence while the outcome is active. It cannot create or list Spools, list events, commit or fund settlement, run verification, or act on another Spool.

Funding and payout setup

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. When Stripe Connect is configured for a production human transaction, the provider completes payout onboarding and the buyer opens hosted Checkout. That adapter creates a manual-capture authorization and acts on the verification result according to its policy.

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. Use the single method-status table when choosing a value.

Troubleshooting by stage

These names come from the REST error registry, receipt verifier, and MCP client. Always branch on the stable code or reason, not the HTTP status alone.

Payment path selection

Payment path selection is fail closed. It considers the actor, amount, currency, configured adapters, declared machine capabilities, readiness, and demo mode. It returns an explicit refusal when no compatible production path qualifies. See Payment paths for the complete model and preview boundaries.

Create a Spool

POST /api/v1/spools

Returns the created canonical Spool with HTTP 201. The request is strict: unknown fields are rejected. This example represents a buyer's $100.00 maximum for 100 enrichment records at $1.00 per accepted record.

{
  "type": "agent_task",
  "parties": [
    { "role": "buyer", "kind": "agent", "display_name": "Buyer agent" },
    { "role": "provider", "kind": "service", "display_name": "Data provider" }
  ],
  "value": { "amount_cents": 10000, "currency": "USD" },
  "deliverable": {
    "type": "dataset", "title": "Enrichment records",
    "description": "100 enrichment records", "attributes": {}
  },
  "terms": [{
    "text": "100 enrichment records at $1.00 per accepted record",
    "provenance": { "source": "user_added", "origin": "user_added" }
  }],
  "conditions": [{
    "description": "Exactly 100 rows", "required": true,
    "verification_method": "deterministic",
    "deterministic_check": { "checker": "row_count", "expected": 100 }
  }]
}

Request fields

• type: goods_in_person, service, digital, or agent_task. Defaults to service.
• parties: exactly two unique display names. Roles are buyer, seller, client, or provider; kinds are human, agent, org, or service. Optional fields are contact, account_id, and a Stripe-style stripe_account_id.
• value: positive integer amount_cents, literal currency USD, and optional rail_preference.
• deliverable: required type, title, description, and string-to-string attributes.
• terms: at least one item with text and provenance. Provenance source is listing, chat, image, freeform, or user_added.
• conditions: an array with description, required flag, and verification method. Deterministic conditions must declare one checker: row_count, completeness, duplicate_rate, url_format, json_path, http_status, text_contains, hash_matches, or deadline_met.
• economics: optional fee_cents and ISO datetime expiry.

Read a Spool

GET /api/v1/spools/{id}

Returns the canonical Spool. The economics.allowed_actions array is computed for the authenticated party. A share ID may also resolve here.

GET /api/v1/spools/{id}/events

Returns the canonical event array in recorded order.

Read and verify an Outcome Receipt

Continue the canonical example by verifying the delivered records. Spoolis accepts 98 records, rejects 2 with reasons, and returns a signed Outcome Receipt recording $98.00 earned. Verify that receipt outside the API with @spoolis/receipt-verifier and pinned receipt keys from the public trust set. Offline signature verification is sufficient. You may then call GET /api/receipts/{id}/status for {receipt_id, status: 'active', advisories: [], checked_at}. After verification and the optional status check, the payment stack may act on the $98.00 earned amount under its own authorization policy.

Verify the underlying attestation

POST /api/v1/attestations/verify

The attestation is the lower-level in-band signed verdict underneath the Outcome Receipt. Send the complete attestation JSON. This public endpoint checks the environment-specific trusted key, signature, digests, expiry, and amount bounds. It returns valid, environment, and machine-readable reasons. It never returns the submitted attestation.

Actions

Send POST /api/v1/spools/{id}/{action}. Lifecycle rules can reject actions that are unavailable in the current state.

Evidence type is one of photo, text, file, url, dataset, or confirmation. Each verify confirmation contains condition_id, method buyer_confirm or both_confirm, outcome passed, failed, or waived, an evidence_refs array, and optional detail.

Errors and rate limits

Every v1 and sandbox error keeps the human-readable error and adds a stable code, retryable flag, and actionable remediation. When relevant, field identifies the failed field or condition path and docs links to help.

{"error":"Invalid API key","code":"unauthenticated","retryable":false,"remediation":"Provide a valid Spoolis API key in the Authorization header.","field":"headers.authorization","docs":"https://spoolis.com/docs/api"}

The implemented v1 limit is 120 requests per minute per account or test-key party label and forwarded IP. A limited request returns 429 with a Retry-After header. When Upstash is not configured, the application currently allows requests without enforcement and logs a warning, so deployments must not assume the limit is active merely because it is documented here.

Binding condition rules

Conditions are binding only when the caller explicitly includes them. Compiler suggestions stay separate until a user or caller adds them. Terms and conditions with unresolved placeholders such as [amount], [date], or TBD are rejected with HTTP 422.