Knowledge

The knowledge store holds documents (uploaded files, pasted text, or Google Drive imports) that agents can search mid-call via the built-in search_knowledge_base tool. Attach documents (or grouping knowledge bases) to an agent with the knowledge_base_ids / knowledge_document_ids fields on Agents. Documents are ingested asynchronously: uploads start in status="pending", move through processing (text extraction for PDF/DOCX, chunking, embedding), and land on ready or failed.

All write operations on this page require the admin role (or an sk_live_ key, which carries full access). Reads are available to every member.

Endpoints

The primary store is flat (“upload-first”) under /v1/knowledge/:

Method	Path	Description
`GET`	`/v1/knowledge/documents`	List documents
`POST`	`/v1/knowledge/documents`	Upload file(s) or create a text document
`GET`	`/v1/knowledge/documents/{document_id}`	Retrieve a document (includes extracted `content`)
`PATCH`	`/v1/knowledge/documents/{document_id}`	Rename / edit text content
`DELETE`	`/v1/knowledge/documents/{document_id}`	Delete a document
`POST`	`/v1/knowledge/documents/{document_id}/retry`	Re-ingest a `failed` document
`GET`	`/v1/knowledge/documents/{document_id}/original`	Download the original uploaded file
`POST`	`/v1/knowledge/documents/{document_id}/replace`	Replace the file behind a document
`POST`	`/v1/knowledge/documents/import-drive`	Import files from Google Drive
`POST`	`/v1/knowledge/search`	Semantic search across documents

Legacy base-scoped routes remain available as adapters (a base is now just a named grouping over the flat store):

Method	Path	Description
`GET` / `POST`	`/v1/knowledge-bases`	List / create knowledge bases
`GET` / `PATCH` / `DELETE`	`/v1/knowledge-bases/{knowledge_base_id}`	Manage one base (delete detaches its documents, it does not delete them)
`GET` / `POST`	`/v1/knowledge-bases/{knowledge_base_id}/documents`	List / create documents inside a base
`PATCH` / `DELETE`	`/v1/knowledge-bases/{knowledge_base_id}/documents/{document_id}`	Manage a document inside a base
`POST`	`/v1/knowledge-bases/{knowledge_base_id}/documents/{document_id}/retry`	Re-ingest
`POST`	`/v1/knowledge-bases/{knowledge_base_id}/search`	Search within one base

Knowledge document object

{
  "id": "8b2f4a1e-…",
  "name": "Refund policy.pdf",
  "source_type": "file",
  "original_filename": "Refund policy.pdf",
  "mime_type": "application/pdf",
  "byte_count": 482113,
  "estimated_chunk_count": 12,
  "status": "ready",
  "error": "",
  "chunk_count": 12,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:31.040Z"
}

Field	Type	Description
`id`	UUID	Document id
`name`	string	Display name
`source_type`	string	`text` (pasted/edited content) or `file` (uploaded)
`original_filename`	string	Empty for text documents
`mime_type`	string	Canonical MIME type (`text/plain`, `text/markdown`, `text/csv`, `application/pdf`, DOCX)
`byte_count`	integer	Size of the original upload (or the UTF-8 text)
`estimated_chunk_count`	integer	Persisted indexed count when ready; otherwise an estimate from current extracted content (falling back to the last persisted count until binary extraction is available)
`status`	string	`pending`, `processing`, `ready`, or `failed`
`error`	string	Ingestion error summary when `failed`
`chunk_count`	integer	Chunks actually indexed
`created_at`, `updated_at`	timestamp

The detail endpoint (GET /v1/knowledge/documents/{id}) adds: content (the canonical extracted text), uploaded_by ({id, name, email} or null), source_origin (upload or google_drive), replaced_at, has_original, original_size_bytes, and original_mime_type.

Upload limits

Kind	Extensions	Max size
Text	`.txt`, `.md`, `.csv`	1 MB
Binary	`.pdf`, `.docx`	50 MB

Anything else is rejected with a 400 field error naming the file.

List documents

curl 'https://api.thunderphone.com/v1/knowledge/documents?status=ready' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Query param	Description
`q`	Substring match on name or content
`status`	`pending`, `processing`, `ready`, `failed`

Returns a plain array of document objects, newest first.

Create documents

Two content types are accepted: Multipart upload — one or more files in files[] (or a single file part, optionally with a name field):

curl -X POST https://api.thunderphone.com/v1/knowledge/documents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -F 'files[]=@refund-policy.pdf' \
  -F 'files[]=@faq.md'

curl -X POST https://api.thunderphone.com/v1/knowledge/documents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Escalation playbook", "content": "When a caller asks for a manager…"}'

JSON — {name, content} creates a source_type="text" document.

Response (201 Created)

{
  "documents": [ /* document objects, status "pending" */ ],
  "warnings": [
    {
      "document_id": "8b2f4a1e-…",
      "duplicate_document_ids": ["77aa…"],
      "message": "This file has the same content as an existing document."
    }
  ]
}

Every file is validated before anything is created — one bad file fails the whole request with 400. Duplicate-content uploads are allowed but reported in warnings.

Retrieve, edit, delete

GET /v1/knowledge/documents/{id} returns the detail shape including extracted content. PATCH accepts JSON {name?, content?} (or a multipart file to swap content). Changing name or content re-queues ingestion (status returns to pending). Returns the updated document. DELETE returns 204 No Content and removes the document and its chunks from the index.

Download the original file

For file-sourced documents, fetch the exact bytes that were uploaded.

curl 'https://api.thunderphone.com/v1/knowledge/documents/8b2f4a1e-…/original?download=1' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns either the file stream directly or a short-lived signed URL:

{ "url": "https://storage.googleapis.com/…", "expires_in": 900 }

download=1 sets an attachment Content-Disposition. Returns 404 when no original is stored (text documents).

Replace the file

POST /v1/knowledge/documents/{id}/replace with a multipart file part swaps the document’s content for the new file (same validation and limits as upload), stores the new original, stamps replaced_at, and re-queues ingestion.

Response

{ "document": { /* document object, status "pending" */ }, "warnings": [] }

If the uploaded bytes are identical to the current file, the request still succeeds and a warning says so.

Retry ingestion

POST /v1/knowledge/documents/{id}/retry re-queues a failed document. Returns the document with status="pending", or 400 with {"detail": "Only failed documents can be retried."} if it is not in failed.

Import from Google Drive

Imports Google Docs (exported to text) and supported Drive files. You supply a short-lived Drive access token obtained client-side (the dashboard uses the Google Picker); ThunderPhone downloads the selected files server-side.

curl -X POST https://api.thunderphone.com/v1/knowledge/documents/import-drive \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "ya29.…",
    "files": [
      { "id": "1AbC…", "name": "Refund policy", "mimeType": "application/vnd.google-apps.document" }
    ]
  }'

Field	Type	Required	Description
`access_token`	string	yes	Google OAuth token with Drive read scope
`files`	array	yes	`{id, name, mimeType}` per file. Google Docs plus `.txt`/`.md`/`.csv`/`.pdf`/`.docx` MIME types are supported; others are `skipped`

Response (201 when anything imported, else 200)

{
  "results": [
    {
      "id": "1AbC…",
      "name": "Refund policy",
      "mimeType": "application/vnd.google-apps.document",
      "status": "imported",
      "document_id": "8b2f4a1e-…",
      "document": { /* document object */ },
      "warnings": []
    }
  ]
}

Per-file status is imported, skipped (unsupported type / oversize), or error — failures never abort the other files.

Search

Semantic (embedding) search over ready documents. This is the same retrieval the agent’s search_knowledge_base tool uses at call time.

curl -X POST https://api.thunderphone.com/v1/knowledge/search \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "what is the refund window?"}'

Field	Type	Required	Description
`query`	string	yes	≤ 4000 chars
`document_ids`	array of UUID	no	Restrict the search scope; omit to search everything

Response

{
  "results": [
    {
      "text": "Refunds are available within 30 days of purchase…",
      "document": "Refund policy.pdf",
      "score": 0.874312
    }
  ]
}

Results are ranked by cosine similarity (score closer to 1 is better), capped per document so one file can’t fill every slot, and each text is length-capped. POST /v1/knowledge-bases/{id}/search takes the same body and scopes the search to that base’s documents.

Knowledge bases (grouping)

A knowledge base is a named group: {id (UUID), name, description, document_count, created_at, updated_at}. Create with POST /v1/knowledge-bases {name, description?} (201); update with PATCH; DELETE (204) detaches the base’s documents back into the flat store without deleting them. Attach whole bases to an agent via knowledge_base_ids.

Agents

Attach documents and bases via knowledge_document_ids / knowledge_base_ids.

Calls

Knowledge lookups appear in the call history as tool calls.

Overview

Organizations

Agents

Phone Numbers

Calls

Billing

Developer

Endpoints

Knowledge document object

Upload limits

List documents

Create documents

Retrieve, edit, delete

Download the original file

Replace the file

Retry ingestion

Import from Google Drive

Search

Knowledge bases (grouping)

Agents

Calls

​Endpoints

​Knowledge document object

​Upload limits

​List documents

​Create documents

​Retrieve, edit, delete

​Download the original file

​Replace the file

​Retry ingestion

​Import from Google Drive

​Search

​Knowledge bases (grouping)

​Related

Agents

Calls

Endpoints

Knowledge document object

Upload limits

List documents

Create documents

Retrieve, edit, delete

Download the original file

Replace the file

Retry ingestion

Import from Google Drive

Search

Knowledge bases (grouping)

Related