---
title: "Compile a sandbox Spool"
method: POST
path: "/api/sandbox/compile"
---

# Compile a sandbox Spool

`POST /api/sandbox/compile`

## Request

- Base URL: `https://spoolis.com`
- URL: `https://spoolis.com/api/sandbox/compile`
- Auth: HTTP bearer

Compiles exact transaction intent into a demo Spool. Optional unitization must reconcile total units and unit amount with the compiled amount and stay within the configured demo record limit.

## Request body

- object
  - `source` string, required
  - `economics` object
    - `unitization` object
      - `total_units` integer, required
      - `unit_amount_cents` integer, required
  - `conditions` object[]
    - `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.
  - `declared_actor_type` unknown

## Response `201`

Compiled demo Spool

- SandboxCompileResult
  - `status` 'compiled', required
  - `spool` Spool, 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
            - `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
  - `compilation` object, required
  - `verification_summary` object[]
    - `description` string, required
    - `method` 'deterministic' | 'buyer_confirm' | 'both_confirm', required
    - `checker` string, nullable, required
    - `downgraded` boolean, required
    - `reason` string
  - `downgrades` CompilerDowngrade[]
    - `condition_ref` string, required
    - `description` string, required
    - `from` string, required
    - `to` string, required
    - `reason` string, 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)