API Reference

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

Base URL

https://api.surfacedocs.dev

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

curl https://api.surfacedocs.dev/v1/documents/doc_abc123 \
  -H "X-API-Key: sd_live_..."

Get your API key from app.surfacedocs.dev.

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.

All errors return a consistent JSON format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid document format",
    "details": {}
  }
}