Write Operations

Write operations let you submit data to PacSpace for verification. Each write records one or more items — key-value pairs with optional metadata — that are batched and verified automatically.

Requires an API key in the X-Api-Key header:

-H "X-Api-Key: pk_live_PUBLIC.SECRET"

Base URL: https://balance-api.pacspace.io

Submit a Write#

Send one or more data items to be recorded and verified.

curl -X POST https://balance-api.pacspace.io/api/v1/writes \
  -H "X-Api-Key: pk_live_PUBLIC.SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "key": "order-12345",
        "accountId": "customer-001",
        "bits": 1,
        "metadata": {
          "amount": 250.00,
          "currency": "USD",
          "description": "Monthly subscription"
        }
      },
      {
        "key": "order-12346",
        "accountId": "customer-002",
        "bits": 3,
        "metadata": {
          "amount": 750.00,
          "currency": "USD",
          "description": "Enterprise license"
        }
      }
    ]
  }'

Response 202 Accepted

{
  "statusCode": 202,
  "data": {
    "batchId": "batch_abc123",
    "itemCount": 2,
    "status": "queued",
    "message": "Write accepted. Items are queued for verification."
  }
}

Request Fields#

How Writes Work#

1. Submit — Your request is accepted and queued for processing
2. Batch — PacSpace groups items for efficient verification
3. Verify — Items are verified and committed to the verification layer
4. Confirm — A webhook notification is sent when verification completes

POST /api/v1/writes → 202 Accepted (queued)
                    → Batched & verified
                    → Webhook: verification.completed

Batch Behavior#

• Items in a single request are processed together as a batch
• Each batch receives a unique batchId for tracking
• Large submissions are automatically split into optimal batch sizes
• Processing typically completes within seconds

Best Practices#

• Use meaningful keys — Record keys should be deterministic and unique (e.g., invoice-2025-001, session-abc-usage)
• Keep metadata lean — Store essential context only; metadata is included in the verification record
• Batch when possible — Sending multiple items per request is more efficient than individual calls
• Set up webhooks — Don't poll for status; use webhooks for real-time confirmation

Error Responses#

See Error Handling for full details.