> ## 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.

# API Reference

> REST API for SurfaceDocs

# API Reference

The SurfaceDocs REST API lets you create, read, and delete documents and manage folders.

## Base URL

```
https://api.surfacedocs.dev
```

## Authentication

All requests require an API key passed in the `X-API-Key` header:

```bash theme={null}
curl https://api.surfacedocs.dev/v1/documents/doc_abc123 \
  -H "X-API-Key: sd_live_..."
```

Get your API key from [app.surfacedocs.dev](https://app.surfacedocs.dev).

## Rate Limits

Rate limits depend on your plan:

| Plan | Per Minute | Per Day |
| ---- | ---------- | ------- |
| Free | 20         | 1,000   |
| Pro  | 300        | 50,000  |

Every response includes rate limit headers:

| Header                  | Description                          |
| ----------------------- | ------------------------------------ |
| `X-RateLimit-Limit`     | Requests allowed per minute          |
| `X-RateLimit-Remaining` | Requests remaining this minute       |
| `X-RateLimit-Reset`     | Unix timestamp when the limit resets |

When rate limited, you'll receive a `429` response with a `Retry-After` header.

## Errors

All errors return a consistent JSON format:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid document format",
    "details": {}
  }
}
```

| HTTP Code | Description                |
| --------- | -------------------------- |
| 400       | Validation error           |
| 401       | Invalid or missing API key |
| 403       | Insufficient permissions   |
| 404       | Resource not found         |
| 429       | Rate limit exceeded        |