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

# Act on a sandbox Spool

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

## Request

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

Models demo acceptance, amends a proposed demo Spool, submits evidence rows, confirms, or verifies a demo Spool. Verification returns a demo attestation. Unitized verification also returns a signed demo Outcome Receipt with units and proportional earned value.

## Path parameters

- `id` string, required
- `action` 'accept' | 'amend' | 'abandon' | 'deliver' | 'evidence' | 'confirm' | 'verify', 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
  - AmendRequest
    - `add_conditions` object[]
    - `remove_condition_ids` string[]
    - `unitization` object
      - `total_units` integer, required
      - `unit_amount_cents` integer, required
  - object

## Response `200`

Sandbox action result

- SandboxActionResult
  - `status` 'completed' | 'saved' | 'limit_reached' | 'resting', required
  - `spool_id` string
  - `spool` Spool
    - `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
  - `attestation` VerificationAttestation
    - `id` string, required
    - `environment` 'production' | 'demo', required
    - `spoolId` string, required
    - `compilationVersion` string, required
    - `verificationPlanVersion` string, required
    - `result` 'pass' | 'partial' | 'fail' | 'uncertain', required
    - `approvedAmount` string, required
    - `maximumAmount` string, required
    - `assetOrCurrency` string, required
    - `payerPartyId` string, required
    - `providerPartyId` string, required
    - `providerDestination` string
    - `conditionResults` object[], required
    - `evidenceDigest` string, required
    - `verificationDigest` string, required
    - `issuedAt` string, date-time, required
    - `expiresAt` string, date-time, required
    - `nonce` string, required
    - `signingKeyId` string, required
    - `signature` string, 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

## 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)