Getting Started
Write Operations
Idempotency keys and dry-run validation, required for every write to the public API.
Idempotency (Write Operations)
All write operations (POST, PUT, DELETE) require an Idempotency-Key header, except media upload (multipart bodies cannot be reliably hashed). This ensures safe retries—if a request is sent twice with the same key and payload, the second request returns the cached response without re-executing.
POST /api/v1/pages
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
Rules
- Max 256 characters
- Keys expire after 24 hours, then can be reused
- Same key + same body → cached response returned (with
X-Idempotency-Replay: trueheader) - Same key + different body →
409 CONFLICT - GET requests do not require idempotency keys
Example Response (Replayed)
HTTP/1.1 201 Created
X-Idempotency-Replay: true
Content-Type: application/json
{
"data": { ... }
}
Dry-Run Validation
All content write endpoints support ?dryRun=true query parameter. This validates the request without persisting data.
Valid Content (POST create):
{
"dryRun": true,
"valid": true,
"errors": [],
"warnings": [],
"wouldCreate": true
}
Valid Content (PUT update):
{
"dryRun": true,
"valid": true,
"errors": [],
"warnings": [],
"wouldUpdate": true
}
Validation Failed (POST create):
{
"dryRun": true,
"valid": false,
"errors": [
{
"path": "fields.title",
"message": "Required field",
"type": "required"
}
],
"warnings": [],
"wouldCreate": false
}
Validation Failed (PUT update):
{
"dryRun": true,
"valid": false,
"errors": [
{
"path": "fields.title",
"message": "Required field",
"type": "required"
}
],
"warnings": [],
"wouldUpdate": false
}