Skip to main content

Push Version

POST /v1/documents/{document_id}/versions
Push a new version of an existing document. The document URL stays the same — viewers always see the latest version.

Request

Headers

HeaderRequiredDescription
X-API-KeyYesYour API key
Content-TypeYesapplication/json

Path Parameters

ParameterTypeRequiredDescription
document_idstringYesThe document ID

Body

FieldTypeRequiredDescription
titlestringYesDocument title
blocksarrayYesArray of content blocks
blocks[].typestringYesBlock type
blocks[].contentstringYesBlock content
blocks[].metadataobjectNoBlock metadata
content_typestringNoDefault: "markdown"
metadataobjectNoDocument-level metadata

Example

curl -X POST https://api.surfacedocs.dev/v1/documents/doc_abc123/versions \
  -H "X-API-Key: sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily Report — Feb 14",
    "blocks": [
      {"type": "heading", "content": "Summary", "metadata": {"level": 1}},
      {"type": "paragraph", "content": "Revenue: $42,000"}
    ],
    "metadata": {"generated_at": "2026-02-14"}
  }'

Response

Status: 201 Created
{
  "id": "doc_abc123",
  "url": "https://app.surfacedocs.dev/d/doc_abc123",
  "version": 2,
  "version_count": 2,
  "title": "Daily Report — Feb 14",
  "block_count": 2,
  "created_at": "2026-02-14T10:30:00Z"
}