Endpoints

Complete REST endpoint reference for prompts, documents, collections, search, and progressive disclosure.

All endpoints require authentication. Include an Authorization header with every request — see Authentication for details.

Replace BASE_URL in the examples below with your Convex deployment's .convex.site URL. See API Overview for base URL derivation.

Prompts

List Prompts

GET /v1/prompts

Auth: prompts.read

Parameter	Type	Required	Description
`limit`	`number`	No	Maximum results to return (default: 20, max: 100)
`cursor`	`string`	No	Pagination cursor from a previous response
`workspace`	`string`	No	Filter by workspace ID
`includePublic`	`string`	No	Include public prompts (`true` or `false`)
`q`	`string`	No	Filter by title or description substring

Example Request

curl -X GET "BASE_URL/v1/prompts?limit=10" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response

{
  "data": [
    {
      "_id": "k57abc123def456",
      "title": "Code Review Prompt",
      "description": "Reviews code for bugs and style issues",
      "content": "Review the following code for potential bugs...",
      "engine": "gpt-4o",
      "createdAt": 1710432000000
    }
  ],
  "pagination": {
    "cursor": "eyIxIjoiMjAifQ==",
    "hasMore": true
  }
}

Get Prompt

GET /v1/prompts/{id}

Auth: prompts.read

Example Request

curl -X GET "BASE_URL/v1/prompts/k57abc123def456" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response

{
  "data": {
    "_id": "k57abc123def456",
    "title": "Code Review Prompt",
    "description": "Reviews code for bugs and style issues",
    "content": "Review the following ${language} code:\n\n${code}",
    "engine": "gpt-4o",
    "variables": [
      { "name": "language", "type": "string" },
      { "name": "code", "type": "string" }
    ],
    "isPublic": false,
    "createdAt": 1710432000000,
    "updatedAt": 1710518400000
  }
}

Create Prompt

POST /v1/prompts

Auth: prompts.read

Field	Type	Required	Description
`title`	`string`	Yes	Prompt title
`description`	`string`	Yes	Brief description
`content`	`string`	Yes	Prompt template content (supports `${variable}` syntax)
`engine`	`string`	Yes	Target AI model identifier
`parameters`	`object`	No	Additional parameters
`variables`	`array`	No	Variable definitions with name, type, and description
`workspaceId`	`string`	No	Workspace to create the prompt in
`tags`	`string[]`	No	Tags for categorization

Example Request

curl -X POST "BASE_URL/v1/prompts" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bug Report Template",
    "description": "Generates structured bug reports",
    "content": "Create a bug report for: ${issue_description}",
    "engine": "gpt-4o"
  }'

Example Response (201 Created)

{
  "data": {
    "_id": "k57xyz789ghi012",
    "title": "Bug Report Template",
    "description": "Generates structured bug reports",
    "content": "Create a bug report for: ${issue_description}",
    "engine": "gpt-4o",
    "createdAt": 1710604800000
  }
}

The response includes a Location header with the new prompt's URL: /v1/prompts/{id}.

Update Prompt

PATCH /v1/prompts/{id}

Auth: prompts.read

Send only the fields you want to change. Updates automatically create a new version.

Field	Type	Required	Description
`title`	`string`	No	New title
`description`	`string`	No	New description
`content`	`string`	No	New content
`parameters`	`object`	No	Updated parameters
`variables`	`array`	No	Updated variable definitions
`changeLog`	`string`	No	Description of changes (saved in version history)

Example Request

curl -X PATCH "BASE_URL/v1/prompts/k57abc123def456" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Review the following ${language} code for bugs, style, and performance:\n\n${code}",
    "changeLog": "Added performance review to scope"
  }'

Example Response

{
  "data": {
    "_id": "k57abc123def456",
    "title": "Code Review Prompt",
    "content": "Review the following ${language} code for bugs, style, and performance:\n\n${code}",
    "updatedAt": 1710691200000
  }
}

Delete Prompt

DELETE /v1/prompts/{id}

Auth: prompts.read

Returns 204 No Content on success with no response body.

Example Request

curl -X DELETE "BASE_URL/v1/prompts/k57abc123def456" \
  -H "Authorization: API-Key cr_your_api_key"

Get Prompt Versions

GET /v1/prompts/{id}/versions

Auth: prompts.read

Returns the version history for a prompt, ordered by creation date.

Example Request

curl -X GET "BASE_URL/v1/prompts/k57abc123def456/versions" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response

{
  "data": [
    {
      "_id": "v_version001",
      "content": "Review the following ${language} code for bugs, style, and performance:\n\n${code}",
      "changeLog": "Added performance review to scope",
      "createdAt": 1710691200000
    },
    {
      "_id": "v_version000",
      "content": "Review the following ${language} code:\n\n${code}",
      "changeLog": "Initial version",
      "createdAt": 1710432000000
    }
  ]
}

Restore Prompt Version

POST /v1/prompts/{id}/restore

Auth: prompts.read

Restores a prompt to a previous version. This creates a new version entry — it doesn't delete the current content.

Field	Type	Required	Description
`versionId`	`string`	Yes	The version ID to restore (from the versions endpoint)

Example Request

curl -X POST "BASE_URL/v1/prompts/k57abc123def456/restore" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "versionId": "v_version000" }'

Example Response

{
  "data": {
    "_id": "k57abc123def456",
    "content": "Review the following ${language} code:\n\n${code}",
    "currentVersion": "v_version002"
  }
}

Documents

List Documents

GET /v1/documents

Auth: documents.read

Parameter	Type	Required	Description
`limit`	`number`	No	Maximum results (default: 20, max: 100)
`cursor`	`string`	No	Pagination cursor
`workspace`	`string`	No	Filter by workspace ID
`collectionId`	`string`	No	Filter by collection ID
`status`	`string`	No	Filter by status
`search`	`string`	No	Filter by title substring
`includeArchived`	`string`	No	Include archived documents (`true` or `false`)
`includeContent`	`string`	No	Include document content in response (`true` or `false`, default: `false`)

Example Request

curl -X GET "BASE_URL/v1/documents?limit=5&includeContent=true" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response

{
  "data": [
    {
      "id": "d_doc123abc",
      "title": "API Design Guidelines",
      "status": "active",
      "isArchived": false,
      "updatedAt": 1710518400000,
      "content": "# API Design Guidelines\n\nThis document outlines..."
    }
  ],
  "pagination": {
    "cursor": "eyIxIjoiNSJ9",
    "hasMore": true
  }
}

When includeContent is true, content is truncated to 2,000 characters in list responses. Use the get-document endpoint for the full text.

Get Document

GET /v1/documents/{id}

Auth: documents.read

Parameter	Type	Required	Description
`includeContent`	`string`	No	Include full content (default: `true`)

Example Request

curl -X GET "BASE_URL/v1/documents/d_doc123abc" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response

{
  "data": {
    "id": "d_doc123abc",
    "title": "API Design Guidelines",
    "status": "active",
    "isArchived": false,
    "createdAt": 1710432000000,
    "updatedAt": 1710518400000,
    "content": "# API Design Guidelines\n\nThis document outlines best practices...",
    "tags": ["engineering", "standards"],
    "sourceType": "manual",
    "sourceUrl": null
  }
}

Create Document

POST /v1/documents

Auth: documents.read

Field	Type	Required	Description
`title`	`string`	Yes	Document title
`content`	`string`	Yes	Document content (plain text or markdown)
`tags`	`string[]`	No	Tags for categorization
`collectionIds`	`string[]`	No	Collections to add the document to
`workspaceId`	`string`	No	Workspace to create the document in

Example Request

curl -X POST "BASE_URL/v1/documents" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting Notes — March 2026",
    "content": "# Key Decisions\n\n- Migrate to v2 API by end of quarter\n- Add webhook support for collections",
    "tags": ["meetings", "planning"]
  }'

Example Response (201 Created)

{
  "data": {
    "id": "d_newdoc456",
    "title": "Meeting Notes — March 2026",
    "status": "active",
    "createdAt": 1710604800000
  }
}

Update Document

PATCH /v1/documents/{id}

Auth: documents.read

Send only the fields you want to change. Updates automatically create a new version.

Field	Type	Required	Description
`title`	`string`	No	New title
`content`	`string`	No	New content
`contentHtml`	`string`	No	HTML version of the content
`metadata`	`object`	No	Additional metadata
`changeLog`	`string`	No	Description of changes (saved in version history)

Example Request

curl -X PATCH "BASE_URL/v1/documents/d_doc123abc" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# API Design Guidelines (Updated)\n\nRevised to include REST and GraphQL...",
    "changeLog": "Added GraphQL section"
  }'

Example Response

{
  "data": {
    "id": "d_doc123abc",
    "title": "API Design Guidelines",
    "updatedAt": 1710691200000
  }
}

Delete Document

DELETE /v1/documents/{id}

Auth: documents.read

Returns 204 No Content on success with no response body.

Example Request

curl -X DELETE "BASE_URL/v1/documents/d_doc123abc" \
  -H "Authorization: API-Key cr_your_api_key"

Get Document Versions

GET /v1/documents/{id}/versions

Auth: documents.read

Returns the version history for a document.

Example Request

curl -X GET "BASE_URL/v1/documents/d_doc123abc/versions" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response

{
  "data": [
    {
      "_id": "dv_version001",
      "changeLog": "Added GraphQL section",
      "createdAt": 1710691200000
    },
    {
      "_id": "dv_version000",
      "changeLog": "Initial version",
      "createdAt": 1710432000000
    }
  ]
}

Restore Document Version

POST /v1/documents/{id}/restore

Auth: documents.read

Restores a document to a previous version by creating a new version with the old content.

Field	Type	Required	Description
`versionId`	`string`	Yes	The version ID to restore

Example Request

curl -X POST "BASE_URL/v1/documents/d_doc123abc/restore" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "versionId": "dv_version000" }'

Example Response

{
  "data": {
    "id": "d_doc123abc",
    "title": "API Design Guidelines",
    "currentVersion": "dv_version002"
  }
}

Scrape URL into Document

POST /v1/documents/scrape

Auth: documents.read

Scrapes a webpage and creates a new document from the extracted content. Uses Firecrawl for intelligent content extraction.

Field	Type	Required	Description
`url`	`string`	Yes	The URL to scrape (auto-prefixed with `https://` if no protocol is provided)
`collectionIds`	`string[]`	No	Collections to add the resulting document to
`options`	`object`	No	Firecrawl extraction options (e.g., `onlyMainContent`, `waitFor`)

Example Request

curl -X POST "BASE_URL/v1/documents/scrape" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/api-design-patterns",
    "collectionIds": ["col_collection123"]
  }'

Example Response (202 Accepted)

{
  "data": {
    "documentId": "d_scraped789"
  }
}

Scraping returns 202 Accepted because extraction happens asynchronously. The document is created and populated in the background. This endpoint has a separate, stricter rate limit than standard CRUD operations.

Collections

List Collections

GET /v1/collections

Auth: documents.read

Parameter	Type	Required	Description
`limit`	`number`	No	Maximum results (default: 20, max: 100)
`cursor`	`string`	No	Pagination cursor (base64-encoded offset)
`search`	`string`	No	Filter by name or description substring
`workspace`	`string`	No	Filter by workspace ID

Example Request

curl -X GET "BASE_URL/v1/collections?limit=10" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response

{
  "data": [
    {
      "id": "col_collection123",
      "name": "Engineering Standards",
      "description": "API guidelines, coding standards, and review checklists",
      "color": "#3b82f6",
      "icon": "📐",
      "isPublic": false,
      "itemCount": 12,
      "lastActivityAt": 1710518400000
    }
  ],
  "pagination": {
    "cursor": "MjA=",
    "hasMore": false
  }
}

Get Collection

GET /v1/collections/{id}

Auth: documents.read

Returns a single collection with its metadata and stats (prompt count, document count).

Example Request

curl -X GET "BASE_URL/v1/collections/col_collection123" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response

{
  "data": {
    "id": "col_collection123",
    "name": "Engineering Standards",
    "description": "API guidelines, coding standards, and review checklists",
    "color": "#3b82f6",
    "icon": "📐",
    "isPublic": false,
    "itemCount": 12,
    "createdAt": 1710432000000,
    "updatedAt": 1710518400000,
    "stats": {
      "promptCount": 5,
      "documentCount": 7
    }
  }
}

Get Collection Items

GET /v1/collections/{id}/items

Auth: documents.read

Returns the prompts and documents in a collection.

Parameter	Type	Required	Description
`limit`	`number`	No	Maximum items (default: 20, max: 100)
`cursor`	`string`	No	Pagination cursor
`includeContent`	`string`	No	Include document content (`true` or `false`)

Example Request

curl -X GET "BASE_URL/v1/collections/col_collection123/items?limit=10" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response

{
  "data": [
    {
      "itemType": "prompt",
      "itemId": "k57abc123def456",
      "title": "Code Review Prompt",
      "summary": "Reviews code for bugs and style issues"
    },
    {
      "itemType": "document",
      "itemId": "d_doc123abc",
      "title": "API Design Guidelines",
      "summary": null
    }
  ],
  "pagination": {
    "cursor": "eyIxIjoiMTAifQ==",
    "hasMore": false
  }
}

Create Collection

POST /v1/collections

Auth: documents.read

Field	Type	Required	Description
`name`	`string`	Yes	Collection name
`description`	`string`	No	Collection description
`color`	`string`	No	Hex color code (e.g., `#3b82f6`)
`icon`	`string`	No	Emoji icon (e.g., `📐`)
`workspaceId`	`string`	No	Workspace to create the collection in
`parentCollectionId`	`string`	No	Parent collection for nesting

Example Request

curl -X POST "BASE_URL/v1/collections" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Roadmap",
    "description": "Planning docs and feature specs",
    "icon": "🗺️",
    "color": "#10b981"
  }'

Example Response (201 Created)

{
  "data": {
    "id": "col_newcol789",
    "name": "Product Roadmap",
    "description": "Planning docs and feature specs",
    "icon": "🗺️",
    "color": "#10b981",
    "createdAt": 1710604800000
  }
}

Update Collection

PATCH /v1/collections/{id}

Auth: documents.read

Send only the fields you want to change.

Field	Type	Required	Description
`name`	`string`	No	New name
`description`	`string`	No	New description
`color`	`string`	No	New hex color code
`icon`	`string`	No	New emoji icon
`isPublic`	`boolean`	No	Make collection public or private

Example Request

curl -X PATCH "BASE_URL/v1/collections/col_collection123" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Engineering Standards v2", "color": "#8b5cf6" }'

Example Response

{
  "data": {
    "id": "col_collection123",
    "name": "Engineering Standards v2",
    "color": "#8b5cf6",
    "updatedAt": 1710691200000
  }
}

Delete Collection

DELETE /v1/collections/{id}

Auth: documents.read

Returns 204 No Content on success. Deleting a collection does not delete the prompts and documents inside it — they remain in your workspace.

Example Request

curl -X DELETE "BASE_URL/v1/collections/col_collection123" \
  -H "Authorization: API-Key cr_your_api_key"

Add Items to Collection

POST /v1/collections/{id}/items

Auth: documents.read

Adds prompts or documents to a collection.

Field	Type	Required	Description
`itemIds`	`string[]`	Yes	Array of prompt or document IDs to add
`itemType`	`string`	Yes	Type of items: `document` or `prompt`

Example Request

curl -X POST "BASE_URL/v1/collections/col_collection123/items" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "itemIds": ["k57abc123def456", "k57xyz789ghi012"],
    "itemType": "prompt"
  }'

Example Response

{
  "data": {
    "added": 2
  }
}

Remove Items from Collection

PUT /v1/collections/{id}/items

Auth: documents.read

Removes prompts or documents from a collection. Uses PUT instead of DELETE because the request requires a JSON body.

Field	Type	Required	Description
`itemIds`	`string[]`	Yes	Array of prompt or document IDs to remove
`itemType`	`string`	Yes	Type of items: `document` or `prompt`

Example Request

curl -X PUT "BASE_URL/v1/collections/col_collection123/items" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "itemIds": ["k57abc123def456"],
    "itemType": "prompt"
  }'

Example Response

{
  "data": {
    "removed": 1
  }
}

Search

Search Across Resources

GET /v1/search

Auth: At least one of prompts.read or documents.read

Searches across prompts, documents, and collections. Supports both semantic (AI embeddings) and literal (substring matching) modes.

Parameter	Type	Required	Description
`q` or `query`	`string`	Yes	Search query
`type`	`string`	No	Filter by type: `prompts`, `documents`, `collections`, or `all` (default: `all`)
`semantic`	`string`	No	Use semantic search (default: `true`). Set to `false` for literal matching
`limit`	`number`	No	Maximum results per type (default: 10, max: 50)
`scoreThreshold`	`number`	No	Minimum relevance score for semantic results (default: 0.35)

Example Request — Semantic Search

curl -X GET "BASE_URL/v1/search?q=API+design+best+practices&type=all" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response — Semantic

{
  "data": {
    "documents": [
      { "documentId": "d_doc123abc", "title": "API Design Guidelines" }
    ],
    "prompts": [
      { "promptId": "k57abc123def456", "title": "Code Review Prompt", "description": "Reviews code for bugs and style issues" }
    ],
    "collections": []
  },
  "meta": {
    "query": "API design best practices",
    "semantic": true,
    "latencyMs": 142
  }
}

Example Request — Literal Search

curl -X GET "BASE_URL/v1/search?q=API+Design&semantic=false&type=documents" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response — Literal

{
  "data": {
    "documents": [
      { "documentId": "d_doc123abc", "title": "API Design Guidelines" }
    ],
    "prompts": [],
    "collections": []
  },
  "meta": {
    "query": "API Design",
    "semantic": false
  }
}

Semantic search uses AI embeddings to find conceptually related content — it doesn't require exact keyword matches. Literal search matches substrings in titles and descriptions.

Progressive Disclosure

Progressive disclosure endpoints let you search and navigate through document content at different levels of detail, from summaries down to individual paragraphs.

Search Content

POST /v1/pd/search

Auth: documents.read

Searches document content with configurable detail level and returns ranked chunks.

Field	Type	Required	Description
`query`	`string`	Yes	Search query
`sessionId`	`string`	No	Session ID for deduplication across searches
`maxTokens`	`number`	No	Maximum tokens in response
`limit`	`number`	No	Maximum chunks to return
`detailLevel`	`string`	No	Detail level for results
`documentId`	`string`	No	Filter to a specific document
`collectionId`	`string`	No	Filter to a specific collection

Example Request

curl -X POST "BASE_URL/v1/pd/search" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication best practices",
    "limit": 5
  }'

Example Response

{
  "data": {
    "chunks": [
      {
        "chunkId": "hc_chunk001",
        "content": "Use JWT tokens with short expiration windows...",
        "level": "section",
        "score": 0.89,
        "documentTitle": "Security Guidelines"
      }
    ],
    "sessionId": "sess_abc123"
  }
}

Expand Chunk

POST /v1/pd/expand

Auth: documents.read

Navigates the document hierarchy from a specific chunk. You can move up (parent), down (children), next/previous (siblings), or get surrounding context.

Field	Type	Required	Description
`chunkId`	`string`	Yes	The chunk ID to expand from
`direction`	`string`	Yes	Navigation direction: `up`, `down`, `next`, `previous`, or `surrounding`
`count`	`number`	No	Number of chunks to return

Example Request

curl -X POST "BASE_URL/v1/pd/expand" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chunkId": "hc_chunk001",
    "direction": "down",
    "count": 3
  }'

Example Response

{
  "data": {
    "chunks": [
      {
        "chunkId": "hc_chunk002",
        "content": "JWT tokens should be signed with RS256...",
        "level": "paragraph"
      }
    ]
  }
}

Read Chunk

GET /v1/pd/read/{chunkId}

Auth: documents.read

Returns a single chunk with its full content and hierarchy metadata.

Example Request

curl -X GET "BASE_URL/v1/pd/read/hc_chunk001" \
  -H "Authorization: API-Key cr_your_api_key"

Example Response

{
  "data": {
    "chunkId": "hc_chunk001",
    "content": "Use JWT tokens with short expiration windows and rotate signing keys regularly.",
    "level": "section",
    "hierarchy": {
      "sectionPath": ["Security Guidelines", "Authentication"],
      "parentChunkId": "hc_parent001"
    },
    "metadata": {
      "wordCount": 14,
      "headingText": "Authentication"
    }
  }
}

Create Session

POST /v1/pd/session

Auth: Any valid authentication

Creates a search session for deduplication. Pass the returned sessionId to the search endpoint to avoid seeing the same chunks across multiple queries.

Field	Type	Required	Description
`ttl`	`number`	No	Session time-to-live in seconds

Example Request

curl -X POST "BASE_URL/v1/pd/session" \
  -H "Authorization: API-Key cr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "ttl": 3600 }'

Example Response (201 Created)

{
  "data": {
    "sessionId": "sess_abc123",
    "expiresAt": 1710608400000
  }
}

MCP Capabilities

Get MCP Capabilities

GET /v1/mcp/capabilities

Auth: None (public)

Returns the MCP protocol capabilities supported by Context Repo.

Example Request

curl -X GET "BASE_URL/v1/mcp/capabilities"

Example Response

{
  "version": "1.0.0",
  "capabilities": {
    "prompts": {
      "rest": true,
      "list": true,
      "get": true,
      "create": true,
      "update": true,
      "delete": true,
      "versions": true,
      "searchQueryParam": true
    },
    "realtime": {
      "subscriptions": true,
      "webhooks": true
    },
    "auth": {
      "bearer": true,
      "apiKey": true
    }
  }
}

Error Codes

All error responses use the same envelope format with a numeric code and a message string:

{
  "error": {
    "code": 404,
    "message": "Document not found"
  }
}

HTTP Status	Meaning	Common Causes
`400`	Bad Request	Missing required fields, invalid JSON body, malformed IDs, invalid parameters
`401`	Unauthorized	Missing `Authorization` header, expired JWT token, invalid API key
`403`	Forbidden	Valid authentication but the API key lacks the required permission scope
`404`	Not Found	Resource doesn't exist or you don't have access to it
`429`	Rate Limited	Too many requests — wait and retry. Rate limit headers are included in the response
`500`	Internal Server Error	Unexpected server error — retry the request or contact support

Authentication

API Overview

Settings

On this page