Skip to main content
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

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:
StatusMeaning
400Invalid request body or query
401Missing or invalid authentication
403Authenticated but not authorized
404Resource not found or not visible
409Slug conflict or concurrent write conflict
503Required external service or billing config missing

​
Common calls

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.