> ## Documentation Index
> Fetch the complete documentation index at: https://surfacedocs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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**

```json theme={null}
{
  "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) |