Endpoints

GET /v1/prompts

curl -X GET "https://api.contextrepo.com/v1/prompts?limit=10" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "data": [
    {
      "id": "k57abc123def456",
      "title": "Code Review Prompt",
      "description": "Reviews code for bugs and style issues",
      "content": "Review the following code for potential bugs...",
      "isPublic": false,
      "currentVersion": 2,
      "tags": ["engineering"],
      "stats": { "views": 42, "copies": 7 }
    }
  ],
  "pagination": {
    "cursor": "eyIxIjoiMjAifQ==",
    "hasMore": true
  }
}

GET /v1/prompts/{id}

curl -X GET "https://api.contextrepo.com/v1/prompts/k57abc123def456" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "data": {
    "id": "k57abc123def456",
    "title": "Code Review Prompt",
    "description": "Reviews code for bugs and style issues",
    "content": "Review the following ${language} code:\n\n${code}",
    "variables": [
      { "name": "language", "type": "string" },
      { "name": "code", "type": "string" }
    ],
    "isPublic": false,
    "isArchived": false,
    "currentVersion": 2,
    "tags": ["engineering"],
    "stats": { "views": 42, "copies": 7 }
  }
}

POST /v1/prompts

curl -X POST "https://api.contextrepo.com/v1/prompts" \
  -H "Authorization: API-Key gm_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}"
  }'

{
  "data": {
    "id": "k57xyz789ghi012",
    "title": "Bug Report Template",
    "description": "Generates structured bug reports",
    "content": "Create a bug report for: ${issue_description}",
    "isPublic": false,
    "isArchived": false,
    "currentVersion": 1,
    "tags": [],
    "stats": { "views": 0, "copies": 0 }
  }
}

PATCH /v1/prompts/{id}

curl -X PATCH "https://api.contextrepo.com/v1/prompts/k57abc123def456" \
  -H "Authorization: API-Key gm_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"
  }'

{
  "data": {
    "id": "k57abc123def456",
    "title": "Code Review Prompt",
    "description": "Reviews code for bugs and style issues",
    "content": "Review the following ${language} code for bugs, style, and performance:\n\n${code}",
    "isPublic": false,
    "isArchived": false,
    "currentVersion": 3,
    "tags": ["engineering"],
    "stats": { "views": 42, "copies": 7 }
  }
}

DELETE /v1/prompts/{id}

curl -X DELETE "https://api.contextrepo.com/v1/prompts/k57abc123def456" \
  -H "Authorization: API-Key gm_your_api_key"

GET /v1/prompts/{id}/versions

curl -X GET "https://api.contextrepo.com/v1/prompts/k57abc123def456/versions" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "data": [
    {
      "id": "v_version001",
      "version": 2,
      "content": "Review the following ${language} code for bugs, style, and performance:\n\n${code}",
      "changeLog": "Added performance review to scope",
      "userName": "Alex Chen"
    },
    {
      "id": "v_version000",
      "version": 1,
      "content": "Review the following ${language} code:\n\n${code}",
      "changeLog": "Initial version",
      "userName": "Alex Chen"
    }
  ]
}

POST /v1/prompts/{id}/restore

curl -X POST "https://api.contextrepo.com/v1/prompts/k57abc123def456/restore" \
  -H "Authorization: API-Key gm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "versionId": "v_version000" }'

{
  "data": {
    "id": "k57abc123def456",
    "title": "Code Review Prompt",
    "description": "Reviews code for bugs and style issues",
    "content": "Review the following ${language} code:\n\n${code}",
    "isPublic": false,
    "isArchived": false,
    "currentVersion": 3,
    "stats": { "views": 42, "copies": 7 }
  }
}

{
  "data": {
    "id": "d_doc123abc",
    "revision": 3,
    "currentVersion": 3,
    "contentHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "lastChangedAt": 1787702400000,
    "noop": false
  }
}

GET /v1/documents

curl -X GET "https://api.contextrepo.com/v1/documents?limit=5&includeContent=true" \
  -H "Authorization: API-Key gm_your_api_key"

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

GET /v1/documents/{id}

curl -X GET "https://api.contextrepo.com/v1/documents/d_doc123abc" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "data": {
    "id": "d_doc123abc",
    "title": "API Design Guidelines",
    "status": "completed",
    "isArchived": false,
    "createdAt": 1710432000000,
    "updatedAt": 1710518400000,
    "revision": 2,
    "currentVersion": 2,
    "contentHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "lastChangedAt": 1710518400000,
    "content": "# API Design Guidelines\n\nThis document outlines best practices...",
    "tags": ["engineering", "standards"],
    "sourceType": "scrape",
    "sourceUrl": "https://example.com/api-guidelines",
    "source": {
      "contentHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "lastCheckedAt": 1787529600000,
      "lastChangedAt": 1787184000000
    }
  }
}

POST /v1/documents/{id}/refresh

curl -X POST "https://api.contextrepo.com/v1/documents/d_doc123abc/refresh" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "data": {
    "documentId": "d_doc123abc",
    "changed": true
  }
}

POST /v1/documents

curl -X POST "https://api.contextrepo.com/v1/documents" \
  -H "Authorization: API-Key gm_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"]
  }'

{
  "data": {
    "id": "d_newdoc456",
    "revision": 0,
    "currentVersion": 0,
    "contentHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "lastChangedAt": 1787702400000,
    "noop": false
  }
}

PATCH /v1/documents/{id}

curl -X PATCH "https://api.contextrepo.com/v1/documents/d_doc123abc" \
  -H "Authorization: API-Key gm_your_api_key" \
  -H 'If-Match: "doc:d_doc123abc:rev:2:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"' \
  -H "Idempotency-Key: update-api-guidelines-3" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# API Design Guidelines (Updated)\n\nRevised to include REST and GraphQL...",
    "changeLog": "Added GraphQL section"
  }'

{
  "data": {
    "id": "d_doc123abc",
    "revision": 3,
    "currentVersion": 3,
    "contentHash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
    "lastChangedAt": 1787702400000,
    "noop": false
  }
}

DELETE /v1/documents/{id}

curl -X DELETE "https://api.contextrepo.com/v1/documents/d_doc123abc" \
  -H "Authorization: API-Key gm_your_api_key"

GET /v1/documents/{id}/versions

curl -X GET "https://api.contextrepo.com/v1/documents/d_doc123abc/versions" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "data": [
    {
      "id": "dv_version001",
      "documentId": "d_doc123abc",
      "version": 2,
      "title": "REST API Reference",
      "content": "# REST API Reference\n\n## GraphQL Section\n\n...",
      "contentHtml": "<h1>REST API Reference</h1><h2>GraphQL Section</h2>...",
      "contentHash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "snapshotCompleteness": "complete",
      "actor": { "kind": "api_key", "displayName": "Docs sync" },
      "origin": "rest",
      "changeLog": "Added GraphQL section",
      "userName": "Alex Chen",
      "createdAt": 1710691200000
    },
    {
      "id": "dv_version000",
      "documentId": "d_doc123abc",
      "version": 1,
      "title": "REST API Reference",
      "content": "# REST API Reference\n\nInitial content...",
      "contentHtml": "<h1>REST API Reference</h1><p>Initial content...</p>",
      "changeLog": "Initial version",
      "userName": "Alex Chen",
      "createdAt": 1710432000000
    }
  ]
}

POST /v1/documents/{id}/restore

curl -X POST "https://api.contextrepo.com/v1/documents/d_doc123abc/restore" \
  -H "Authorization: API-Key gm_your_api_key" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "doc:d_doc123abc:rev:2:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"' \
  -H "Idempotency-Key: restore-api-guidelines-2" \
  -d '{ "versionId": "dv_version000" }'

{
  "data": {
    "id": "d_doc123abc",
    "revision": 3,
    "currentVersion": 3,
    "contentHash": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
    "lastChangedAt": 1787702400000,
    "noop": false
  }
}

GET /v1/documents/{id}/coordination

PUT /v1/documents/{id}/coordination

If-Match: "<exact ETag from GET>"
Idempotency-Key: <unique retry key>
X-ContextRepo-Lease-Id: <lease ID>
X-ContextRepo-Lease-Fence: <fence number>

DELETE /v1/documents/{id}/coordination

POST /v1/documents/{id}/coordination/lease

POST /v1/documents/scrape

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

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

GET /v1/collections

curl -X GET "https://api.contextrepo.com/v1/collections?limit=10" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "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 /v1/collections/{id}

curl -X GET "https://api.contextrepo.com/v1/collections/col_collection123" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "data": {
    "id": "col_collection123",
    "name": "Engineering Standards",
    "description": "API guidelines, coding standards, and review checklists",
    "color": "#3b82f6",
    "icon": "📐",
    "isPublic": false,
    "tags": ["engineering"],
    "itemCount": 12,
    "lastActivityAt": 1710518400000,
    "createdAt": 1710432000000,
    "updatedAt": 1710518400000
  }
}

GET /v1/collections/{id}/items

curl -X GET "https://api.contextrepo.com/v1/collections/col_collection123/items?limit=10" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "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
  }
}

POST /v1/collections

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

{
  "data": {
    "id": "col_newcol789",
    "name": "Product Roadmap",
    "description": "Planning docs and feature specs",
    "icon": "🗺️",
    "color": "#10b981",
    "isPublic": false,
    "tags": [],
    "itemCount": 0,
    "lastActivityAt": 1710604800000,
    "createdAt": 1710604800000,
    "updatedAt": 1710604800000
  }
}

PATCH /v1/collections/{id}

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

{
  "data": {
    "id": "col_collection123",
    "name": "Engineering Standards v2",
    "description": "API guidelines, coding standards, and review checklists",
    "color": "#8b5cf6",
    "icon": "📐",
    "isPublic": false,
    "tags": ["engineering"],
    "itemCount": 12,
    "lastActivityAt": 1710518400000,
    "createdAt": 1710432000000,
    "updatedAt": 1710691200000
  }
}

DELETE /v1/collections/{id}

curl -X DELETE "https://api.contextrepo.com/v1/collections/col_collection123" \
  -H "Authorization: API-Key gm_your_api_key"

POST /v1/collections/{id}/items

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

{
  "data": {
    "added": 2,
    "alreadyInCollection": 0
  }
}

PUT /v1/collections/{id}/items

curl -X PUT "https://api.contextrepo.com/v1/collections/col_collection123/items" \
  -H "Authorization: API-Key gm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "itemIds": ["k57abc123def456"],
    "itemType": "prompt"
  }'

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

GET /v1/search

curl -X GET "https://api.contextrepo.com/v1/search?q=API+design+best+practices&type=all" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "data": {
    "documents": [
      {
        "documentId": "d_doc123abc",
        "title": "API Design Guidelines",
        "score": 0.87,
        "highlight": "...every endpoint declares explicit request and response contracts...",
        "tags": ["engineering", "standards"]
      }
    ],
    "prompts": [
      {
        "promptId": "k57abc123def456",
        "title": "Code Review Prompt",
        "description": "Reviews code for bugs and style issues",
        "score": 0.74,
        "tags": ["engineering"]
      }
    ],
    "collections": []
  },
  "meta": {
    "query": "API design best practices",
    "semantic": true,
    "latencyMs": 142
  }
}

curl -X GET "https://api.contextrepo.com/v1/search?q=API+Design&semantic=false&type=documents" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "data": {
    "documents": [
      {
        "documentId": "d_doc123abc",
        "title": "API Design Guidelines",
        "tags": ["engineering", "standards"],
        "highlight": "...every endpoint in our API Design standard declares explicit request and response contracts...",
        "chunkId": "hc_chunk789xyz"
      }
    ],
    "prompts": [],
    "collections": []
  },
  "meta": {
    "query": "API Design",
    "semantic": false
  }
}

?tags=draft,roadmap-q3

```bash title="Example — search across all types, scoped to a project tag"
curl -X GET "https://api.contextrepo.com/v1/search?q=migration&tags=customer-x" \
  -H "Authorization: API-Key gm_your_api_key"

POST /v1/pd/search

curl -X POST "https://api.contextrepo.com/v1/pd/search" \
  -H "Authorization: API-Key gm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication best practices",
    "limit": 5
  }'

{
  "data": {
    "results": [
      {
        "chunkId": "hc_chunk001",
        "content": "Use JWT tokens with short expiration windows...",
        "level": "section",
        "score": 0.89,
        "parentId": "hc_parent001",
        "siblingIds": { "prev": null, "next": "hc_chunk002" },
        "documentId": "d_doc123abc",
        "documentTitle": "Security Guidelines"
      }
    ],
    "meta": { "query": "authentication best practices", "totalResults": 1, "latencyMs": 142 }
  }
}

POST /v1/pd/expand

curl -X POST "https://api.contextrepo.com/v1/pd/expand" \
  -H "Authorization: API-Key gm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chunkId": "hc_chunk001",
    "direction": "down",
    "count": 3
  }'

{
  "data": {
    "chunks": [
      {
        "_id": "hc_chunk002",
        "content": "JWT tokens should be signed with RS256...",
        "level": "paragraph",
        "parentId": "hc_chunk001",
        "chunkIndex": 0,
        "documentId": "d_doc123abc",
        "documentTitle": "Security Guidelines"
      }
    ]
  }
}

GET /v1/pd/read/{chunkId}

curl -X GET "https://api.contextrepo.com/v1/pd/read/hc_chunk001" \
  -H "Authorization: API-Key gm_your_api_key"

{
  "data": {
    "chunkId": "hc_chunk001",
    "content": "Use JWT tokens with short expiration windows and rotate signing keys regularly.",
    "level": "section",
    "hierarchy": {
      "documentId": "d_doc123abc",
      "documentTitle": "Security Guidelines",
      "sectionPath": "Security Guidelines > Authentication",
      "position": {
        "chunkIndex": 2,
        "parentChunkId": "hc_parent001",
        "prevSiblingId": null,
        "nextSiblingId": "hc_chunk002"
      }
    },
    "metadata": {
      "startIndex": 1042,
      "endIndex": 1138,
      "wordCount": 14,
      "sectionPath": "Security Guidelines > Authentication",
      "headingText": "Authentication"
    }
  }
}

POST /v1/pd/session

curl -X POST "https://api.contextrepo.com/v1/pd/session" \
  -H "Authorization: API-Key gm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "ttl": 3600 }'

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

POST /v1/reason

curl -X POST "https://api.contextrepo.com/v1/reason" \
  -H "Authorization: API-Key gm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What is our refund policy for annual plans?", "limit": 8 }'

{
  "data": {
    "answer": "Annual plans are refundable within the first 14 days...",
    "citations": [
      {
        "chunkId": "hc_chunk001",
        "documentId": "doc_abc123",
        "documentTitle": "Billing Policy",
        "score": 0.82
      }
    ],
    "gaps": ["No stated policy for partial-year downgrades"],
    "conflicts": [],
    "meta": {
      "chunksGathered": 8,
      "citationsDropped": 0,
      "latencyMs": 1840
    }
  }
}

GET /v1/mcp/capabilities

curl -X GET "https://api.contextrepo.com/v1/mcp/capabilities"

{
  "version": "1.0.0",
  "capabilities": {
    "prompts": {
      "rest": true,
      "list": true,
      "get": true,
      "create": true,
      "update": true,
      "delete": true,
      "versions": true,
      "searchQueryParam": true
    },
    "documents": {
      "rest": true,
      "list": true,
      "get": true,
      "create": true,
      "update": true,
      "delete": true,
      "versions": true,
      "scrape": true
    },
    "collections": {
      "rest": true,
      "list": true,
      "get": true,
      "create": true,
      "update": true,
      "delete": true,
      "items": true
    },
    "search": { "rest": true },
    "progressiveDisclosure": {
      "search": true,
      "expand": true,
      "read": true,
      "session": true
    },
    "reason": { "rest": true },
    "auth": { "bearer": true, "apiKey": true }
  }
}

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