---
title: "Create a Spool"
method: POST
path: "/api/v1/spools"
---

# Create a Spool

`POST /api/v1/spools`

## Request

- Base URL: `https://spoolis.com`
- URL: `https://spoolis.com/api/v1/spools`
- Auth: HTTP bearer

Creates a proposed Spool from a strict canonical request.

## Request body

- CreateSpoolRequest
  - `gated_action` 'payment' | 'workflow_step' | 'publish' | 'merge' | 'delegation' | 'other': Declared intent only: what the caller says this Outcome gates. Not verified.
  - `gated_action_note` string: Optional caller-declared context. Not verified.
  - `agreement` object
    - `mode` 'bilateral' | 'unilateral', required
  - `type` 'goods_in_person' | 'service' | 'digital' | 'agent_task'
  - `parties` object[], required
    - `role` 'buyer' | 'seller' | 'client' | 'provider', required
    - `kind` 'human' | 'agent' | 'org' | 'service', required
    - `display_name` string, required
    - `binding` 'external': Present on the non-binding provider in unilateral mode.
    - `contact` string
    - `account_id` string
    - `settlement_address` string
    - `stripe_account_id` string
  - `value` object, required
    - `amount_cents` integer, required
    - `currency` 'USD', required
    - `rail_preference` string
  - `deliverable` object, required
    - `type` string, required
    - `title` string, required
    - `description` string, required
    - `attributes` object, required
  - `terms` object[], required
    - `text` string, required
    - `provenance` object, required
  - `conditions` object[], required
    - `description` string, required
    - `required` boolean, required
    - `verification_method` 'buyer_confirm' | 'both_confirm' | 'deterministic' | 'ai_assisted' | 'third_party', required
    - `deterministic_check` object: claim_cited requires verification_method ai_assisted. Every other checker requires deterministic.
      - `checker` 'row_count' | 'completeness' | 'duplicate_rate' | 'url_format' | 'json_path' | 'http_status' | 'text_contains' | 'hash_matches' | 'deadline_met' | 'claim_cited', required
    - `evidence_requirements` object[]
      - `id` string, required
      - `expected_type` string, required
      - `source` object, required
        - `ref` string, required
        - `description` string
      - `provenance` object
        - `min_class` 'submitted_by_provider' | 'submitted_by_buyer' | 'fetched_by_spoolis' | 'signed_by_external_system' | 'confirmed_by_human' | 'unknown_origin'
        - `independent_of` 'provider' | 'buyer'
      - `who_may_supply` string[]
      - `freshness_seconds` integer
      - `on_missing` 'uncertain' | 'fail'
    - `external_judge` object
      - `evaluator_id` string, required
      - `kind` 'external_service' | 'zk_verifier' | 'marketplace_evaluator' | 'buyer_owned' | 'ai_evaluator' | 'human_arbitration', required
      - `evaluator_version` string
      - `proof_requirement` 'signed' | 'hashed_ref' | 'declared', required
      - `on_missing` 'uncertain' | 'fail'
      - `public_key` string: PEM public key required for signed proof verification.
  - `economics` object
    - `unitization` object
      - `total_units` integer
      - `unit_amount_cents` integer
      - `identity` object: Publishes a salted identity.id per unit. label visibility also publishes the source value; the private per-Spool salt is never in the receipt.
        - `key` string, required
        - `visibility` 'label' | 'pseudonymous', required
  - `dispute_policy` object: Hash-covered semantic policy declaration. A party named in who_may_dispute can supersede an issued receipt through POST /api/v1/receipts/{receipt_id}/supersede. There is no review queue or UI.

## Response `201`

Created Spool

- SpoolCreated
  - `id` string, required
  - `schema_version` 1, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `type` 'goods_in_person' | 'service' | 'digital' | 'agent_task', required
  - `status` object, required
    - `agreement` 'draft' | 'proposed' | 'accepted' | 'declined' | 'cancelled', required
    - `fulfillment` string, required
    - `verification` string, required
    - `settlement` string, required
    - `outcome` string, required
  - `initiator_party_id` string, required
  - `parties` object[], required
  - `value` object, required
  - `deliverable` object, required
  - `terms` object[], required
  - `conditions` object[], required
  - `evidence` object[], required
  - `verification` object, required
  - `settlement` object, required
    - `mode` 'direct_eip3009' | 'unattended_outcome_settlement'
    - `direct_signer` 'principal_runtime'
    - `grant` SettlementGrant
      - `permission_hash` string, required
      - `chain_id` integer, required
      - `manager_address` string, required
      - `permission` SpendPermission, required
        - `account` string, required
        - `spender` string, required
        - `token` string, required
        - `allowance` string, required
        - `period` integer, required
        - `start` integer, required
        - `end` integer, required
        - `salt` string, required
        - `extraData` string, required
      - `creation_tx_hash` string
      - `revoke_url` string, required
      - `preview` unknown, required
  - `economics` object
  - `events` object[], required
  - `receipt` OutcomeReceipt: Signed spoolis/outcome-receipt@1 artifact.
    - `recipe` object
      - `slug` string, required
      - `hash` string, required
      - `conditions` object[], required
    - `agreement` object
      - `acceptance` object
        - `mode` 'unilateral', required
        - `provider_accepted_in_spoolis` unknown, required
        - `accepted_by` 'initiator', required
    - `amounts` object
      - `earned` string, required
      - `committed` string: Omitted when verification ran without max_amount_cents.
      - `asset` string, required
      - `decimals` integer, required
    - `condition_results` object[]
      - `required_evidence` object[]
        - `requirement_id` string, required
        - `state` 'present' | 'missing' | 'stale' | 'unavailable' | 'provenance_unsatisfied', required
        - `satisfied` boolean, required
        - `evidence_ref` string
        - `reason` string
    - `evidence_completeness` object
      - `required` integer, required
      - `satisfied` integer, required
      - `missing` integer, required
      - `stale` integer, required
      - `unavailable` integer, required
      - `unsatisfied_provenance` integer, required
    - `units` object
      - `unit_results` object[]
        - `identity` object
          - `id` string, required: SHA-256 over the private per-Spool salt and unit identity value.
          - `label` string
    - `supersedes` object
      - `receipt_id` string, required
      - `reason` 'verification_defect' | 'appeal_reversal' | 'dispute_resolution' | 'review_decision', required: Backward link to the receipt replaced by a correction, dispute resolution, or human review decision.
    - `review` object
      - `window_seconds` integer, required
      - `window_ends_at` string, date-time, required
      - `who_may_dispute` string[], required
      - `scope` 'outcome' | 'units', required
      - `on_dispute` 'freeze_all' | 'freeze_disputed_value', required
  - `receipt_url` string, uri-reference
  - `verification_binding` VerificationBinding, required
    - `agreement_hash` string, required
    - `evidence_root` string, required
    - `unit_ids` string[]
  - `terminal` boolean, required
  - `settlement_eligible` boolean, required
  - `can_resubmit_evidence` boolean, required
  - `can_rerun` boolean, required
  - `next_step` NextStep, required: Spoolis says what happened; the consuming system decides what happens next. next_step names an available interaction with Spoolis or the transaction state, never a command about money or deployment.
    - `type` 'settle' | 'submit_evidence' | 'rerun_allowed' | 'await_confirmation' | 'sign_settlement' | 'terminal' | 'new_spool', required
    - `action` 'settle' | 'submit_evidence' | 'rerun_allowed' | 'await_confirmation' | 'sign_settlement' | 'terminal' | 'new_spool', required: Deprecated v1 compatibility alias for type.
    - `actor` 'buyer' | 'provider' | 'verifier' | 'none', required
    - `reason` string, required
    - `required_legs` string[]
    - `settlement_request` DirectSettlementRequest
      - `domain` object, required
      - `types` object, required
      - `primaryType` 'TransferWithAuthorization', required
      - `seller` object, required
      - `fee` object, required
    - `submit_url` string
  - `decision_authority` 'deterministic' | 'buyer_confirmation' | 'both_confirm' | 'none', required

## Other responses

- `400`: Machine-readable API error
- `401`: Machine-readable API error
- `403`: Machine-readable API error
- `404`: Machine-readable API error
- `409`: Machine-readable API error
- `413`: Machine-readable API error
- `422`: Machine-readable API error
- `429`: Machine-readable API error
- `500`: Machine-readable API error
- `503`: Machine-readable API error

---

[API](https://skmtc.dev/spoolis/apis/spoolis-public-api.md) · [All operations](https://skmtc.dev/spoolis/apis/spoolis-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spoolis/apis/spoolis-public-api/revisions/e438bfc05c01?raw)