Create Document

POST /v1/documents

Create Document

POST /v1/documents

Create a new document with blocks. Requires the documents:write role.

Request

Headers

Header	Required	Description
X-API-Key	Yes	Your API key
Content-Type	Yes	application/json

Body

Field	Type	Required	Description
title	string	Yes	Document title (max 500 characters)
blocks	array	Yes	Array of content blocks
blocks[].type	string	Yes	Block type: heading, paragraph, code, list, quote, table, image, divider
blocks[].content	string	Yes	Block content
blocks[].metadata	object	No	Block metadata (e.g., level for headings)
folder_id	string	No	Target folder ID. Uses root folder if omitted.
content_type	string	No	Default: "markdown"
visibility	string	No	"private" (default) or "public"
metadata	object	No	Document-level metadata

Example

curl -X POST https://api.surfacedocs.dev/v1/documents \
  -H "X-API-Key: sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Guide",
    "blocks": [
      {"type": "heading", "content": "Overview", "metadata": {"level": 1}},
      {"type": "paragraph", "content": "Welcome to the API."}
    ]
  }'

Response

Status: 201 Created

{
  "id": "doc_abc123",
  "url": "https://app.surfacedocs.dev/d/doc_abc123",
  "folder_id": "fld_xyz",
  "title": "API Guide",
  "content_type": "markdown",
  "block_count": 2,
  "metadata": null,
  "visibility": "private",
  "created_at": "2025-01-15T10:30:00Z"
}

Quota Headers

Responses include document quota information:

Header	Description
X-Quota-Used	Documents created this month
X-Quota-Limit	Monthly document limit
X-Quota-Reset	Date when quota resets (YYYY-MM-DD)