Developers
API keysOpen app
API Reference

API Reference

Every endpoint lives under /api/v1 and requires a Bearer key. Requests and responses are JSON. The default answer model is deepseek-chat.

Errors

Every endpoint returns the same error envelope on failure. Check the error.code for programmatic handling and surface error.message to humans.

json
{
  "error": {
    "code": "not_found",
    "message": "Knowledge base not found."
  }
}
StatuscodeWhen
400bad_requestMalformed body, missing required field, or invalid value.
401unauthorizedMissing, malformed, or invalid API key.
403forbiddenValid key, but no access to the requested knowledge base or action.
404not_foundThe requested resource does not exist (or is not visible to your key).
500 / 503server_errorUnexpected error or a transient upstream/model outage. Retry with backoff.

Endpoints

GET/api/v1/me

Verify a key and return the calling account’s identity.

bash
curl http://localhost:3000/api/v1/me \
  -H "Authorization: Bearer dq_live_YOUR_KEY"

Response

json
{
  "id": "3f29a9e1-7c44-4b6a-9e21-8a1b6d0f2c77",
  "email": "you@example.com"
}

GET/api/v1/knowledge-bases

List all knowledge bases your key can reach — owned plus shared read-only.

bash
curl http://localhost:3000/api/v1/knowledge-bases \
  -H "Authorization: Bearer dq_live_YOUR_KEY"

Response

json
{
  "knowledge_bases": [
    {
      "id": "b9993782-087d-482c-861e-3cc0fad3cbca",
      "name": "Product Docs",
      "description": "Internal product documentation",
      "role": "owner",
      "document_count": 12,
      "is_default": true,
      "created_at": "2026-06-22T09:14:02Z"
    },
    {
      "id": "d4a1e6f0-52b3-4c9a-8e17-f6a2b9c04d31",
      "name": "Shared Research",
      "description": "Read-only KB shared with me",
      "role": "viewer",
      "document_count": 48,
      "is_default": false,
      "created_at": "2026-05-03T11:40:18Z"
    }
  ]
}

role is one of owner, viewer (shared with you directly), org-member (visible to your whole org), or library (a curated KB). Only owners can write documents or delete the KB.

POST/api/v1/knowledge-bases

Create a new knowledge base you own. Returns 201.

FieldTypeRequiredDescription
namestringyesDisplay name for the KB.
descriptionstringnoOptional short description.
bash
curl -X POST http://localhost:3000/api/v1/knowledge-bases \
  -H "Authorization: Bearer dq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support KB", "description": "Help-desk articles" }'

Response (201 Created)

json
{
  "knowledge_base": {
    "id": "1c7e4a92-0f3d-4b8e-a6c5-9d2e871b04af",
    "name": "Support KB",
    "description": "Help-desk articles",
    "is_default": false,
    "created_at": "2026-06-22T10:02:55Z"
  }
}

GET/api/v1/knowledge-bases/{id}

Fetch a single knowledge base by id.

ParamTypeRequiredDescription
idstringyesPath parameter — the knowledge-base id.
bash
curl http://localhost:3000/api/v1/knowledge-bases/b9993782-087d-482c-861e-3cc0fad3cbca \
  -H "Authorization: Bearer dq_live_YOUR_KEY"

Response

json
{
  "knowledge_base": {
    "id": "b9993782-087d-482c-861e-3cc0fad3cbca",
    "name": "Product Docs",
    "description": "Internal product documentation",
    "role": "owner",
    "is_default": true,
    "created_at": "2026-06-22T09:14:02Z"
  }
}

DELETE/api/v1/knowledge-bases/{id}

Delete a knowledge base and its documents. Owner-only.

ParamTypeRequiredDescription
idstringyesPath parameter — the KB to delete. Must be owned by your key.
bash
curl -X DELETE http://localhost:3000/api/v1/knowledge-bases/1c7e4a92-0f3d-4b8e-a6c5-9d2e871b04af \
  -H "Authorization: Bearer dq_live_YOUR_KEY"

Response

json
{ "deleted": true, "mode": "soft" }

Returns 403 forbidden if you are not the owner. Deletion is soft by default (recoverable) — the response's mode field reflects which kind actually happened.

GET/api/v1/knowledge-bases/{id}/documents

List the documents inside a knowledge base.

ParamTypeRequiredDescription
idstringyesPath parameter — the knowledge-base id.
bash
curl http://localhost:3000/api/v1/knowledge-bases/b9993782-087d-482c-861e-3cc0fad3cbca/documents \
  -H "Authorization: Bearer dq_live_YOUR_KEY"

Response

json
{
  "documents": [
    {
      "id": "6e2f0a8c-9b41-4d7e-8a3f-c05e9b1d7264",
      "filename": "refunds.md",
      "title": "refunds",
      "source": "api",
      "created_at": "2026-06-22T09:20:11Z"
    },
    {
      "id": "a15d9c3e-6b72-4f08-9e41-3c8a0d5f7b92",
      "filename": "onboarding.md",
      "title": "onboarding",
      "source": "upload",
      "created_at": "2026-06-21T15:02:44Z"
    }
  ]
}

source records how the document entered the KB (e.g. api or upload).

POST/api/v1/documents

Ingest raw text or markdown into a KB you own. Chunks and embeds automatically. Returns 201.

FieldTypeRequiredDescription
kb_idstringyesTarget knowledge base. You must own it.
filenamestringyesName shown in listings and citations.
contentstringyesRaw text or markdown body to index.
bash
curl -X POST http://localhost:3000/api/v1/documents \
  -H "Authorization: Bearer dq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_id": "b9993782-087d-482c-861e-3cc0fad3cbca",
    "filename": "refunds.md",
    "content": "# Refund policy\nRefunds are issued within 14 days of purchase."
  }'

Response (201 Created)

json
{
  "document": {
    "id": "6e2f0a8c-9b41-4d7e-8a3f-c05e9b1d7264",
    "filename": "refunds.md",
    "title": "refunds",
    "chunks": 1,
    "total_chunks": 1
  }
}

chunks / total_chunks report how many segments were produced. v1 ingests text and markdown; ingest PDFs through the app.

POST/api/v1/query

Ask a question. Hybrid (dense + sparse RRF) retrieval scoped to your KBs, answered with DeepSeek and returned with citations.

FieldTypeRequiredDescription
querystringyesThe natural-language question.
knowledge_base_idsstring[]noRestrict retrieval to these KBs. Omit to search every KB your key can reach.
modelstringnoAnswer model. Defaults to deepseek-chat.
max_resultsnumbernoMaximum retrieved chunks to ground the answer on.
include_chunksbooleannoWhen true, returns the raw retrieved chunks alongside the answer for debugging.
bash
curl -X POST http://localhost:3000/api/v1/query \
  -H "Authorization: Bearer dq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How long do customers have to request a refund?",
    "knowledge_base_ids": ["b9993782-087d-482c-861e-3cc0fad3cbca"],
    "model": "deepseek-chat",
    "max_results": 6,
    "include_chunks": false
  }'

Response

json
{
  "answer": "Customers can request a refund within 14 days of purchase.",
  "citations": [
    {
      "document_id": "6e2f0a8c-9b41-4d7e-8a3f-c05e9b1d7264",
      "title": "refunds.md",
      "snippet": "Refunds are issued within 14 days of purchase.",
      "similarity": 0.91
    }
  ],
  "model": "deepseek-chat",
  "knowledge_base_ids": ["b9993782-087d-482c-861e-3cc0fad3cbca"]
}

citations[] shape

FieldTypeDescription
document_idstringThe source document the snippet came from.
titlestringThe document’s filename / title.
snippetstringThe exact passage the answer drew from.
similaritynumberRetrieval relevance score (0–1, higher is closer).

The response echoes the resolved model and knowledge_base_ids so you can confirm exactly what was searched.