Write Operations
Submit write operations to record data in PacSpace's verification layer.
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 verified automatically.
Requires an API key in the X-Api-Key header:
bash
-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.
bash
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
json
{
"statusCode": 202,
"data": {
"requestId": "req_abc123",
"itemCount": 2,
"status": "queued",
"message": "Write accepted. Items are queued for verification."
}
}
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
items | array | Yes | One or more items to record |
items[].key | string | Yes | Unique record identifier (e.g., order ID, transaction ID) |
items[].accountId | string | Yes | The account or entity this record belongs to |
items[].bits | number | Yes | Integer value representing the data delta (e.g., quantity, amount) |
items[].metadata | object | No | Arbitrary key-value data to store alongside the record |
How Writes Work
- Submit — Your request is accepted and queued for processing
- Verify — Items are verified and committed to the verification layer
- Confirm — A webhook notification is sent when verification completes
POST /api/v1/writes → 202 Accepted (queued)
→ Verified
→ Webhook: verification.completed
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
- Send multiple items per request — Submitting items together is more convenient than individual calls
- Set up webhooks — Don't poll for status; use webhooks for real-time confirmation
Error Responses
| Status | Meaning |
|---|---|
400 | Invalid request body — check required fields |
401 | Invalid or missing API key |
402 | Plan limit exceeded — upgrade or wait for the next billing period |
429 | Rate limit exceeded — back off and retry |
500 | Server error — retry with exponential backoff |
See Error Handling for full details.