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.

A workspace is the top-level organizational container in Caret. Every folder and document belongs to exactly one workspace, and users collaborate within workspaces through a membership model. Workspaces come in two kinds: personal (a private home space automatically provisioned for each user) and shared (team workspaces that multiple members can be invited to). The Workspaces API lets you create and manage these containers, control membership, and rename or remove workspaces as your team structure evolves. 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/workspaces* traffic to the internal document-service. Always target https://api.caret.page/api/v1/... from client code.

​
POST /api/v1/workspaces

Create a new workspace. The caller is automatically added as the workspace owner. Shared workspaces can be built out with additional members using the invite endpoint. Request body
​
name
string
required
Display name for the workspace. Shown in the workspace switcher and sidebar header.
​
slug
string
Optional URL-friendly identifier for the workspace. Must be unique. If omitted, a slug is auto-generated from the workspace name using a citext uniqueness check.
​
kind
string
Workspace kind: "shared" (default, for team workspaces) or "personal" (private home workspace). Personal workspaces are normally provisioned automatically — you will only need this field in special circumstances.
Response — 201 Created
​
id
string
UUID of the newly created workspace.
​
slug
string | null
URL-friendly slug. Auto-generated if not provided at creation time.
​
name
string
Display name of the workspace.
​
kind
string
Workspace kind — "personal" or "shared".
​
created_by_user_id
string | null
UUID of the user who created the workspace. Set to the caller’s user ID.
​
role
string
The caller’s role in this workspace. The creator always starts as "owner".
​
shared_with
string[]
Array of email addresses of other active members (excluding the caller). Empty on creation.
​
created_at
string
ISO 8601 timestamp of when the workspace was created.
​
updated_at
string
ISO 8601 timestamp of the last update to the workspace record.
curl -X POST https://api.caret.page/api/v1/workspaces \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Engineering",
    "slug": "acme-engineering",
    "kind": "shared"
  }'

{
  "id": "w1a2b3c4-d5e6-f789-0abc-def123456789",
  "slug": "acme-engineering",
  "name": "Acme Engineering",
  "kind": "shared",
  "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
  "role": "owner",
  "shared_with": [],
  "created_at": "2024-11-01T09:00:00.000Z",
  "updated_at": "2024-11-01T09:00:00.000Z"
}

​
GET /api/v1/workspaces

List all workspaces the authenticated caller is a member of, regardless of their role within those workspaces. The response includes both the caller’s personal workspace and any shared workspaces they have been invited to. Each entry includes the caller’s current role and the shared_with list of co-member emails. Query parameters
​
limit
number
Maximum number of workspaces to return. Omit for unpaginated results.
​
offset
number
Number of workspaces to skip before returning results. Used together with limit for cursor-style pagination.
Response — 200 OK — array of WorkspaceResponseDto Returns an array of workspace objects. Each object has the same shape as the response documented in POST /api/v1/workspaces above. 
curl -X GET https://api.caret.page/api/v1/workspaces \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "w1a2b3c4-d5e6-f789-0abc-def123456789",
    "slug": "acme-engineering",
    "name": "Acme Engineering",
    "kind": "shared",
    "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
    "role": "owner",
    "shared_with": ["teammate@acme.com"],
    "created_at": "2024-11-01T09:00:00.000Z",
    "updated_at": "2024-11-01T09:00:00.000Z"
  },
  {
    "id": "w9z8y7x6-w5v4-u321-tsrq-ponmlkjihgfe",
    "slug": "my-personal-space",
    "name": "My Personal Space",
    "kind": "personal",
    "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
    "role": "owner",
    "shared_with": [],
    "created_at": "2024-10-01T08:00:00.000Z",
    "updated_at": "2024-10-01T08:00:00.000Z"
  }
]

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

Rename an existing workspace. Only the workspace name can be changed through this endpoint. To change workspace kind or slug, contact support or manage those properties through Supabase directly.
The gateway spec uses PATCH for this operation. Only the fields you include are updated; omitted fields remain unchanged.
Path parameters
​
id
string
required
UUID of the workspace to update.
Request body
​
name
string
Updated display name for the workspace. This is the only mutable field via the API.
Response — 200 OK — WorkspaceResponseDto Returns the full updated workspace object. 
curl -X PATCH https://api.caret.page/api/v1/workspaces/w1a2b3c4-d5e6-f789-0abc-def123456789 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Platform Engineering"
  }'

{
  "id": "w1a2b3c4-d5e6-f789-0abc-def123456789",
  "slug": "acme-engineering",
  "name": "Acme Platform Engineering",
  "kind": "shared",
  "created_by_user_id": "u1a2b3c4-d5e6-f789-0abc-def123456789",
  "role": "owner",
  "shared_with": ["teammate@acme.com"],
  "created_at": "2024-11-01T09:00:00.000Z",
  "updated_at": "2024-11-06T14:30:00.000Z"
}

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

Soft-delete a workspace. The workspace is marked as deleted via a deleted_at timestamp and will no longer appear in list responses. All documents and folders in the workspace are implicitly inaccessible after deletion. Only the workspace owner can perform this action.
Deleting a workspace is a soft delete — the record is retained in the database with deleted_at set. All associated documents, folders, and membership records remain in the database but are filtered from all API responses. This action cannot be reversed through the API.
Path parameters
​
id
string
required
UUID of the workspace to delete.
Response — 204 No Content No response body is returned on successful deletion. 
curl -X DELETE https://api.caret.page/api/v1/workspaces/w1a2b3c4-d5e6-f789-0abc-def123456789 \
  -H "Authorization: Bearer <token>"

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

Invite a user to join a workspace by their email address. The user must already have a registered Caret account. If the user is already a member of the workspace, the operation reactivates their membership. Invited members are assigned the member role; workspace ownership can only be transferred out-of-band.
Workspace membership gives the invited user access to all documents with visibility: "workspace" within that workspace, plus any documents they are directly invited to. It does not automatically grant access to documents with visibility: "private".
Path parameters
​
id
string
required
UUID of the workspace to invite the user to.
Request body
​
email
string
required
Email address of the user to invite. The user must have an existing Caret account.
Response — 201 Created
​
workspace_id
string
UUID of the workspace the user was invited to.
​
user_id
string
UUID of the invited user, resolved from the provided email.
​
email
string
Email address of the invited user, as provided in the request.
​
role
string
Role assigned to the invited user. Always "member" for workspace invites.
curl -X POST https://api.caret.page/api/v1/workspaces/w1a2b3c4-d5e6-f789-0abc-def123456789/invite \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newmember@acme.com"
  }'

{
  "workspace_id": "w1a2b3c4-d5e6-f789-0abc-def123456789",
  "user_id": "u3c4d5e6-f7a8-9012-bcde-f23456789012",
  "email": "newmember@acme.com",
  "role": "member"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us