Caret REST API: Base URL, Versioning, and Error Codes

The Caret REST API gives you programmatic access to every resource in the platform — documents, workspaces, folders, AI conversations, suggestions, and vector embeddings. Every request flows through a single API Gateway that handles CORS, rate limiting, and proxy routing to the appropriate microservice. All endpoints speak JSON, all errors follow the same shape, and all protected routes require a Supabase-issued JWT in the Authorization header.

Base URLs

Caret exposes two environments. Use the production URL for real workloads and the local URL when running the stack with Docker Compose.

Environment	Base URL
Production	`https://api.caret.page/api/v1`
Local development	`http://localhost:3000/api/v1`

The API version (v1) is embedded in the URL path. When a new version ships it will appear as /api/v2 alongside the existing prefix, giving you time to migrate without a hard cut-over.

Authentication

Every protected endpoint requires a valid Supabase JWT. Pass it as a Bearer token in the Authorization header on each request:

Authorization: Bearer <supabase-jwt>

Requests that arrive without a valid token receive a 401 Unauthorized response. Requests that carry a valid token but lack the required permissions receive 403 Forbidden. See the Authentication guide for full details on obtaining and refreshing tokens.

Response Format

All responses — success and error alike — are JSON objects. Content-Type is always application/json.

Successful responses

Successful responses return the resource object or an array of resource objects directly. HTTP status codes follow REST conventions:

Status	Meaning
`200 OK`	Request succeeded; body contains the result
`201 Created`	Resource was created; body contains the new resource
`204 No Content`	Request succeeded; no body (typically DELETE)

Error responses

Every error response follows the ErrorResponseDto schema — a single error field containing a human-readable message:

{
  "error": "Human-readable error message"
}

error

string

required

A human-readable description of what went wrong. Suitable for logging and debugging; do not display raw values directly to end users without sanitisation.

Common error status codes:

Status	Meaning
`401 Unauthorized`	Missing or invalid JWT
`403 Forbidden`	Valid JWT but insufficient permissions
`422 Unprocessable Entity`	Request body failed schema validation
`500 Internal Server Error`	Unexpected server-side failure

Health and Discovery Endpoints

Two endpoints are available without authentication and are useful for liveness checks and service discovery.

GET /api/v1

Returns gateway metadata including the service name, API version string, and the list of route prefixes the gateway proxies. Use this to confirm the gateway is reachable and to discover available resource prefixes.

curl https://api.caret.page/api/v1

{
  "service": "caret-api-gateway",
  "version": "v1",
  "endpoints": ["/api/v1/documents", "/api/v1/workspaces", "..."]
}

GET /health

Returns the liveness status of the API Gateway. Integrate this into your load balancer or uptime monitor — it is intentionally lightweight and requires no token.

curl https://api.caret.page/health

{
  "status": "ok",
  "service": "api-gateway"
}

Versioning

The current public API version is v1. The version is encoded directly in the URL path (/api/v1/...) rather than in a header, making it explicit and easy to audit in logs and network captures. Future versions will introduce a new path prefix (/api/v2/...) and coexist with v1 during any deprecation window.

Pin your integrations to the versioned path. Never use a versionless base URL — unversioned paths may be removed without notice.

Complete Endpoint Inventory

The table below lists every route exposed through the API Gateway. Routes marked with the 🔒 icon require a valid Authorization: Bearer header. The two gateway/health endpoints are unauthenticated.

Method	Path	Description	Auth
`GET`	`/api/v1`	API Gateway info and route prefixes	—
`GET`	`/health`	Gateway liveness check	—
`POST`	`/api/v1/documents`	Create a document in a workspace	🔒
`GET`	`/api/v1/documents`	List documents in a workspace	🔒
`GET`	`/api/v1/documents/shared`	List documents shared directly with the caller	🔒
`GET`	`/api/v1/documents/{id}`	Get a single document by ID	🔒
`PATCH`	`/api/v1/documents/{id}`	Update document title, placement, or content	🔒
`DELETE`	`/api/v1/documents/{id}`	Soft-delete a document	🔒
`POST`	`/api/v1/documents/{id}/invite`	Invite a collaborator to a document	🔒
`POST`	`/api/v1/workspaces`	Create a workspace	🔒
`GET`	`/api/v1/workspaces`	List workspaces visible to the caller	🔒
`PATCH`	`/api/v1/workspaces/{id}`	Update a workspace	🔒
`DELETE`	`/api/v1/workspaces/{id}`	Soft-delete a workspace	🔒
`POST`	`/api/v1/workspaces/{id}/invite`	Invite a member to a workspace	🔒
`POST`	`/api/v1/folders`	Create a folder in a workspace	🔒
`GET`	`/api/v1/folders`	List folders in a workspace (optionally filtered by parent)	🔒
`GET`	`/api/v1/folders/all`	List all folders in a workspace as a flat tree-building payload	🔒
`PATCH`	`/api/v1/folders/{id}`	Update a folder’s name, parent, or sort order	🔒
`DELETE`	`/api/v1/folders/{id}`	Soft-delete a folder	🔒
`GET`	`/api/v1/ai/models`	Fetch the curated AI model catalog	🔒
`POST`	`/api/v1/ai/conversations`	Create an AI conversation for a document	🔒
`GET`	`/api/v1/ai/conversations`	List AI conversations for a document	🔒
`GET`	`/api/v1/ai/conversations/{conversation_id}/messages`	Fetch all messages in a conversation	🔒
`DELETE`	`/api/v1/ai/conversations/{conversation_id}`	Delete an AI conversation	🔒
`POST`	`/api/v1/ai/conversations/{conversation_id}/touch`	Mark a conversation as recently used	🔒
`POST`	`/api/v1/ai/conversations/{conversation_id}/stream`	Stream an AI response via Server-Sent Events (SSE)	🔒
`PATCH`	`/api/v1/ai/suggestions/{suggestion_id}/status`	Update the lifecycle status of a suggestion	🔒
`POST`	`/api/v1/ai/embeddings/index`	Index document text into the vector store for RAG retrieval	🔒

Documents and workspaces use soft deletes — a deleted_at timestamp is set rather than a hard DELETE at the database level. Resources with a non-null deleted_at are filtered from list responses automatically.

Explore by Resource

Use the links below to dive into each resource area with full request/response schemas, parameter descriptions, and runnable curl examples.

Documents

Create, read, update, soft-delete, and share documents. Documents belong to a workspace and optionally to a folder.

Workspaces

Manage personal and shared workspaces. Invite members and control top-level access.

Folders

Organise documents into a nested folder hierarchy within a workspace.

AI Conversations

Create conversations, fetch message history, and stream AI responses over SSE.

AI Suggestions

Accept, dismiss, or supersede AI-generated text suggestions through their lifecycle.

Embeddings

Index document text into the pgvector store to power context-aware RAG retrieval.

Collaboration WebSocket

Connect directly to the collab service for real-time Y.js sync and awareness — bypasses the API Gateway.

Overview

Documents & Workspaces

AI & Collaboration

Caret REST API: Base URL, Versioning, and Error Codes

Base URLs

Authentication

Response Format

Successful responses

Error responses

Health and Discovery Endpoints

GET /api/v1

GET /health

Versioning

Complete Endpoint Inventory

Explore by Resource

Documents

Workspaces

Folders

AI Conversations

AI Suggestions

Embeddings

Collaboration WebSocket

Build docs developers (and LLMs) love

Overview

Documents & Workspaces

AI & Collaboration

Documentation Index

​Base URLs

​Authentication

​Response Format

​Successful responses

​Error responses

​Health and Discovery Endpoints

GET /api/v1

GET /health

​Versioning

​Complete Endpoint Inventory

​Explore by Resource

Documents

Workspaces

Folders

AI Conversations

AI Suggestions

Embeddings

Collaboration WebSocket

Build docs developers (and LLMs) love

Base URLs

Authentication

Response Format

Successful responses

Error responses

Health and Discovery Endpoints

Versioning

Complete Endpoint Inventory

Explore by Resource