---
title: "Act on a Spool"
method: POST
path: "/api/v1/spools/{id}/{action}"
---

# Act on a Spool

`POST /api/v1/spools/{id}/{action}`

## Request

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

Performs one documented lifecycle action using the action-specific body. Each evidence item is capped at 1 MB; larger material should be referenced by URL or digest. External-result stores a declared evaluator judgment as evidence; it becomes runnable only for a matching external_judge declaration. Agent accept requests must carry the current quote_digest. Amend changes conditions or unitization on a proposed Spool before acceptance and requires the full-scope key of the Spool creator. Counterparty keys can accept, decline, and submit evidence only on their bound active Spool. They cannot create, commit, fund, verify, or list events. Verify-scoped keys can submit evidence and run verification before settlement is committed. Abandon, commit, provider payout onboarding, and verification that would release a committed settlement require a full-scope key. Abandon is available to either party only while the outcome is active and settlement is uncommitted. Verification includes the Outcome Receipt and its lower-level attestation when signing is configured.

## Path parameters

- `id` string, required
- `action` 'propose' | 'accept' | 'amend' | 'decline' | 'cancel' | 'abandon' | 'commit' | 'evidence' | 'external-result' | 'verify' | 'complete' | 'onboard-provider', required

## Request body

- union
  - EvidenceRequest
    - `condition_id` string, required
    - `type` 'photo' | 'text' | 'file' | 'url' | 'dataset' | 'confirmation', required
    - `source` string, required
    - `submitted_by` string
    - `on_behalf_of` string
    - `provenance` 'api_response' | 'uploaded_json' | 'url_fetch' | 'external_tool_result'
    - `metadata` object
  - ExternalResultRequest
    - `evaluator` object, required
      - `id` string, required
      - `kind` 'external_service' | 'zk_verifier' | 'marketplace_evaluator' | 'buyer_owned' | 'ai_evaluator' | 'human_arbitration', required
      - `version` string
    - `verdict` 'pass' | 'fail' | 'uncertain', required
    - `condition_results` object[], required
      - `condition_ref` string, required
      - `result` 'pass' | 'fail' | 'uncertain', required
      - `reason` string
    - `evidence_refs` string[]
    - `proof` object, required
      - `kind` 'signature' | 'hashed_ref' | 'declared', required
      - `ref` string
      - `sha256` string
      - `algorithm` string
    - `observed_at` string, date-time, required
  - CommitRequest
    - `payment_method` string
    - `direct_signer` 'principal_runtime'
    - `settlement_mode` 'direct_eip3009' | 'unattended_outcome_settlement'
  - AmendRequest
    - `add_conditions` object[]
    - `remove_condition_ids` string[]
    - `unitization` object
      - `total_units` integer, required
      - `unit_amount_cents` integer, required
  - object
    - `quote_digest` string, required
  - object

## Response `200`

Updated Spool or action-specific result

- union
  - SpoolRead
    - `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
  - object
    - `spool` SpoolRead, required
      - `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
              - …
        - `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
    - `account_id` string
    - `onboarding_url` string, uri

## Other responses

- `400`: Machine-readable API error
- `401`: Machine-readable API error
- `402`: Usage balance is required before the quoted work can execute
- `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)