Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/arrozet/caret/llms.txt

Use this file to discover all available pages before exploring further.

Documents are the core content unit in Caret. Every document lives inside a workspace and can optionally be placed in a folder within that workspace. The Documents API gives you full control over the document lifecycle — from creating a blank page and writing structured content, to sharing it with collaborators at fine-grained permission levels. Content is stored in two parallel representations: a structured Tiptap/ProseMirror JSON tree (content_json) that the rich-text editor consumes, and a plain-text extraction (content_text) used for search and AI context. All endpoints require a valid Supabase JWT passed as a Bearer token.
All endpoints are routed through the API Gateway. The gateway forwards /api/v1/documents* traffic to the internal document-service. You should always target https://api.caret.page/api/v1/... in client code.

​
POST /api/v1/documents

Create a new document inside a workspace. The caller is automatically set as the document owner. The document is created with an empty body — use PATCH /api/v1/documents/{id} to write content after creation. Request body
​
title
string
required
Display title for the document. Shown in the workspace sidebar and document header.
​
workspace_id
string
required
UUID of the workspace the document will belong to. The caller must be a member of this workspace.
​
folder_id
string
UUID of the folder to place the document in. Omit (or pass null) to create the document at the workspace root.
Response — 201 Created
​
id
string
UUID of the newly created document.
​
workspace_id
string
UUID of the workspace this document belongs to.
​
folder_id
string | null
UUID of the containing folder, or null if the document is at the workspace root.
​
title
string
Document title as provided at creation time.
​
status
string
Lifecycle status. Newly created documents start as active. Can also be archived.
​
visibility
string
Access scope. One of private, workspace, link, or public.
​
owner_user_id
string | null
UUID of the user who owns the document. Set to the caller’s user ID on creation.
​
content_json
object | null
Latest Tiptap/ProseMirror JSON content tree. null for a newly created empty document.
​
content_text
string | null
Plain-text extraction of the document content. null for a newly created empty document.
​
created_at
string
ISO 8601 timestamp of when the document was created.
​
updated_at
string
ISO 8601 timestamp of the last update to the document record.
curl -X POST https://api.caret.page/api/v1/documents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q3 Product Roadmap",
    "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "folder_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef"
  }'

{
  "id": "d9e8f7a6-b5c4-3210-fedc-ba9876543210",
  "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "folder_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
  "title": "Q3 Product Roadmap",
  "status": "active",
  "visibility": "private",
  "owner_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
  "content_json": null,
  "content_text": null,
  "created_at": "2024-11-01T09:00:00.000Z",
  "updated_at": "2024-11-01T09:00:00.000Z"
}

​
GET /api/v1/documents

List all documents in a given workspace that the caller has access to. Returns documents the caller owns or is an explicit member of within the specified workspace. This endpoint does not return documents shared directly with the caller from other workspaces — use GET /api/v1/documents/shared for those. Query parameters
​
workspace_id
string
required
UUID of the workspace to list documents from.
​
limit
number
Maximum number of documents to return. Omit for unpaginated results.
​
offset
number
Number of documents to skip before returning results. Used together with limit for cursor-style pagination.
Response — 200 OK — array of DocumentResponseDto Returns an array of document objects. Each object has the same shape as the response documented in POST /api/v1/documents above. 
curl -X GET "https://api.caret.page/api/v1/documents?workspace_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "d9e8f7a6-b5c4-3210-fedc-ba9876543210",
    "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "folder_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "title": "Q3 Product Roadmap",
    "status": "active",
    "visibility": "private",
    "owner_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
    "content_json": null,
    "content_text": null,
    "created_at": "2024-11-01T09:00:00.000Z",
    "updated_at": "2024-11-01T09:00:00.000Z"
  }
]

​
GET /api/v1/documents/shared

List all documents that have been shared directly with the authenticated caller — that is, documents where the caller has been added as an explicit document-level collaborator (editor, commenter, or viewer), regardless of workspace membership. This is useful for building “Shared with me” views.
This endpoint has no required query parameters. It automatically scopes results to the authenticated user’s direct document memberships across all workspaces.
Response — 200 OK — array of DocumentResponseDto Returns an array of document objects using the same shape as other document endpoints. 
curl -X GET https://api.caret.page/api/v1/documents/shared \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "c8d7e6f5-a4b3-2109-edcb-a98765432109",
    "workspace_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "folder_id": null,
    "title": "Design System Guidelines",
    "status": "active",
    "visibility": "private",
    "owner_user_id": "u9a8b7c6-d5e4-f321-0fed-cba987654321",
    "content_json": null,
    "content_text": "Design tokens, spacing scale, and component patterns...",
    "created_at": "2024-10-15T14:30:00.000Z",
    "updated_at": "2024-10-20T11:00:00.000Z"
  }
]

​
GET /api/v1/documents/{id}

Retrieve a single document by its UUID. The response includes the full content_json and content_text fields when content has been saved. The caller must have at least viewer access to the document. Path parameters
​
id
string
required
UUID of the document to retrieve.
Response — 200 OK — DocumentResponseDto
​
id
string
UUID of the document.
​
workspace_id
string
UUID of the workspace this document belongs to.
​
folder_id
string | null
UUID of the containing folder, or null if the document is at the workspace root.
​
title
string
Document title.
​
status
string
Lifecycle status — active or archived.
​
visibility
string
Access scope — private, workspace, link, or public.
​
owner_user_id
string | null
UUID of the document owner.
​
content_json
object | null
The latest saved Tiptap/ProseMirror JSON content tree. null if no content has been written yet.
​
content_text
string | null
Plain-text extraction of the latest document content. Used for search and AI context injection. null if no content has been written yet.
​
created_at
string
ISO 8601 creation timestamp.
​
updated_at
string
ISO 8601 timestamp of the last update.
curl -X GET https://api.caret.page/api/v1/documents/d9e8f7a6-b5c4-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer <token>"

{
  "id": "d9e8f7a6-b5c4-3210-fedc-ba9876543210",
  "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "folder_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
  "title": "Q3 Product Roadmap",
  "status": "active",
  "visibility": "workspace",
  "owner_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
  "content_json": {
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": { "level": 1 },
        "content": [{ "type": "text", "text": "Q3 Product Roadmap" }]
      },
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "This document outlines planned features..." }]
      }
    ]
  },
  "content_text": "Q3 Product Roadmap\nThis document outlines planned features...",
  "created_at": "2024-11-01T09:00:00.000Z",
  "updated_at": "2024-11-05T16:20:00.000Z"
}

​
PATCH /api/v1/documents/{id}

Update a document’s title, folder placement, workspace assignment, or rich-text content. All fields are optional — only the fields you include will be changed. This is the primary write path for the editor: the Tiptap frontend sends content_json and content_text together whenever the user saves.
The gateway spec uses PATCH for this operation (partial update semantics). Only fields you include in the request body will be modified; omitted fields are left unchanged.
Path parameters
​
id
string
required
UUID of the document to update.
Request body — all fields optional
​
title
string
New title for the document.
​
workspace_id
string
Move the document to a different workspace by supplying its UUID. The caller must have write access in the target workspace.
​
folder_id
string | null
Move the document to a different folder. Pass a folder UUID to move into a folder, or null to move the document to the workspace root.
​
content_json
object
Updated Tiptap/ProseMirror JSON content tree. Should be sent together with content_text.
​
content_text
string
Updated plain-text extraction of the document content. Used by the AI service for RAG indexing. Should be sent together with content_json.
Response — 200 OK — DocumentResponseDto Returns the full updated document object. 
curl -X PATCH https://api.caret.page/api/v1/documents/d9e8f7a6-b5c4-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q3 Product Roadmap (Updated)",
    "content_json": {
      "type": "doc",
      "content": [
        {
          "type": "heading",
          "attrs": { "level": 1 },
          "content": [{ "type": "text", "text": "Q3 Product Roadmap (Updated)" }]
        }
      ]
    },
    "content_text": "Q3 Product Roadmap (Updated)"
  }'

{
  "id": "d9e8f7a6-b5c4-3210-fedc-ba9876543210",
  "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "folder_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
  "title": "Q3 Product Roadmap (Updated)",
  "status": "active",
  "visibility": "workspace",
  "owner_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
  "content_json": {
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": { "level": 1 },
        "content": [{ "type": "text", "text": "Q3 Product Roadmap (Updated)" }]
      }
    ]
  },
  "content_text": "Q3 Product Roadmap (Updated)",
  "created_at": "2024-11-01T09:00:00.000Z",
  "updated_at": "2024-11-06T10:15:00.000Z"
}

​
DELETE /api/v1/documents/{id}

Soft-delete a document by its UUID. The document is marked as deleted in the database but not permanently removed, preserving audit history and allowing potential recovery. Only the document owner or a workspace owner can delete a document.
Deletion is a soft delete — the deleted_at timestamp is set on the record. The document will no longer appear in list or get responses, but it is not immediately purged from the database.
Path parameters
​
id
string
required
UUID of the document to delete.
Response — 204 No Content No response body is returned on successful deletion. 
curl -X DELETE https://api.caret.page/api/v1/documents/d9e8f7a6-b5c4-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer <token>"

​
POST /api/v1/documents/{id}/invite

Invite a user to collaborate on a specific document by their email address. The invited user is found by email in the Caret user directory and granted a direct document-level role. Document-level sharing is distinct from workspace membership — a user can be given access to a single document without becoming a workspace member. The response scope field is always "document", distinguishing this invite from workspace-level membership recorded by the workspaces invite endpoint. Collaboration roles
RolePermissions
ownerFull control, including inviting others and deleting the document
editorCan read and write document content
commenterCan read content and leave comments
viewerRead-only access
Path parameters
​
id
string
required
UUID of the document to invite the collaborator to.
Request body
​
email
string
required
Email address of the user to invite. The user must already have a Caret account.
Response — 201 Created
​
document_id
string
UUID of the document the collaborator was invited to.
​
user_id
string
UUID of the invited user.
​
email
string
Email address of the invited user, as provided in the request.
​
role
string
The role granted to the invited user. One of owner, editor, commenter, or viewer.
​
scope
string
Always "document" for this endpoint, indicating a direct document-level share (as opposed to workspace-level membership).
curl -X POST https://api.caret.page/api/v1/documents/d9e8f7a6-b5c4-3210-fedc-ba9876543210/invite \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "collaborator@example.com"
  }'

{
  "document_id": "d9e8f7a6-b5c4-3210-fedc-ba9876543210",
  "user_id": "u2b3c4d5-e6f7-8901-abcd-ef2345678901",
  "email": "collaborator@example.com",
  "role": "editor",
  "scope": "document"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us