REST API

The canonical HTTP surface behind the web app, CLI, and MCP server.

The REST API is the canonical application surface. The web app, CLI, and MCP server all call the same domain services behind these routes — so behavior is consistent no matter how you connect.

This page covers conventions and common calls. For the full endpoint list, see the REST API reference.

Base URLs

Local (direct)

http://127.0.0.1:3001

Authentication

Browser sessions use Better Auth cookies through /api/auth/*. Automation uses bearer auth:

curl "$API_URL/api/profile/me" \
  -H "authorization: Bearer $TOKEN"

Bearer-authenticated requests skip CSRF checks, which makes them convenient for scripts and services.

Response shape

Most JSON routes return either a domain object or an object wrapping a collection:

{
  "artifacts": []
}

Create routes return 201 on success. Raw content routes can return source text with content headers instead of JSON.

Errors

Domain errors map to stable HTTP categories:

Status	Meaning
400	Invalid request body or query
401	Missing or invalid authentication
403	Authenticated but not authorized
404	Resource not found or not visible
409	Slug conflict or concurrent write conflict
503	Required external service or billing config missing

Common calls

Create artifact

curl -X POST "$API_URL/api/artifacts" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "ownerUsername": "alice",
    "projectSlug": "default",
    "slug": "report",
    "type": "md",
    "title": "Report",
    "content": "# Report",
    "access": { "publicView": true, "publicEdit": false }
  }'

Path resolution is handy when an agent has a URL-like identity and needs the artifact ID for later operations.

MCP metadata

The API also serves the OAuth metadata MCP clients need:

GET  /.well-known/oauth-protected-resource
GET  /.well-known/oauth-authorization-server
POST /mcp

REST API reference

Every endpoint, grouped by resource, with request bodies.