Knowledge Base

The knowledge base lets you augment an agent with reference material - FAQs, product details, pricing, policies, or any domain-specific content - without stuffing it all into the system prompt. Each entry is chunked and embedded so the agent can retrieve the most relevant passages during a conversation.

Entries are scoped to a single agent and live under /agents/{agent_id}/knowledge. Every endpoint accepts the same authentication as the rest of the public API: send your key in the X-API-Key header (a Bearer JWT also works). The base URL is https://api.usevocals.com/api/v1.

Ingestion Lifecycle

Creating an entry is asynchronous. The create endpoints return 201 Created immediately with status set to pending; the content is then chunked and embedded in the background. Poll the entry until it settles:

1. Create a text, url, or file entry -> 201 with status: "pending".
2. Background ingestion runs (chunking + embedding). Status moves through processing to ready.
3. Poll GET /agents/{agent_id}/knowledge/{entry_id} until status is ready (usable) or error.
4. If status is error, the reason is in error_message.

If an entry lands in error with an embeddings or authentication message, the agent's tenant needs a working embedding provider configured - either an OpenAI provider or the platform's managed embeddings. Once that is in place, call the reprocess endpoint to retry the entry.

Entry Schema

KnowledgeEntryResponse is returned by the list, get, and create endpoints.

Field	Type	Description
id	uuid	Entry ID
agent_id	uuid	Owning agent ID
subagent_id	uuid | null	The subagent this source is scoped to, or null for an agent-wide source
source_type	string	text, url, or file
title	string	Entry title
source_url	string | null	Source URL (URL entries only)
file_size_bytes	integer | null	Uploaded file size (file entries only)
mime_type	string | null	Detected MIME type (file entries only)
status	string	pending, processing, ready, or error
error_message	string | null	Failure reason when status is error (e.g. an embeddings error)
chunk_count	integer	Number of embedded chunks produced
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Endpoints

Method	Path	Purpose
GET	/agents/{agent_id}/knowledge/	List the agent's entries (newest first); add ?subagent_id= for one subagent's
POST	/agents/{agent_id}/knowledge/text	Create an entry from raw text
POST	/agents/{agent_id}/knowledge/url	Create an entry from a web URL
POST	/agents/{agent_id}/knowledge/file	Create an entry from an uploaded file
GET	/agents/{agent_id}/knowledge/{entry_id}	Fetch a single entry
DELETE	/agents/{agent_id}/knowledge/{entry_id}	Delete an entry (and its chunks + stored file)
POST	/agents/{agent_id}/knowledge/{entry_id}/reprocess	Re-run ingestion for an entry

The collection root (/agents/{agent_id}/knowledge/) only supports GET. To create an entry, post to one of the text, url, or file sub-paths - posting to the bare root returns 405 Method Not Allowed.

Each agent can hold up to 50 entries by default; creating another beyond the cap returns 400 Bad Request.

Every create route accepts an optional subagent_id (a form field on the file upload, a body field on the others) that scopes the entry to one subagent rather than the whole agent. Scoped entries count against the same cap. A scoped entry is only searched while that subagent is answering: the main agent and the agent's other subagents never retrieve from it.

List Entries

GET /agents/{agent_id}/knowledge/

Returns all entries for the agent, newest first.

curl -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "9f8b7c6d-1234-4a5b-9c8d-abcdef012345",
    "source_type": "text",
    "title": "Refund Policy",
    "source_url": null,
    "file_size_bytes": null,
    "mime_type": null,
    "status": "ready",
    "error_message": null,
    "chunk_count": 3,
    "created_at": "2026-06-01T10:30:00Z",
    "updated_at": "2026-06-01T10:30:12Z"
  }
]

Create Text Entry

POST /agents/{agent_id}/knowledge/text

Request Body

{
  "title": "Refund Policy",
  "content": "Refunds are available within 30 days of purchase..."
}

Field	Type	Required	Description
title	string	Yes	Entry title
content	string	Yes	Raw text to ingest

curl -X POST https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/text \
  -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund Policy",
    "content": "Refunds are available within 30 days of purchase..."
  }'

Response

201 Created - Returns the KnowledgeEntryResponse with status: "pending". Ingestion runs in the background.

Create URL Entry

POST /agents/{agent_id}/knowledge/url

Fetches the page at the given URL and ingests its content in the background.

Request Body

{
  "url": "https://example.com/docs/pricing",
  "title": "Pricing Page"
}

Field	Type	Required	Description
url	string	Yes	URL to fetch and ingest
title	string | null	No	Optional title; derived from the page when omitted

curl -X POST https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/url \
  -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/docs/pricing",
    "title": "Pricing Page"
  }'

Response

201 Created - Returns the KnowledgeEntryResponse with status: "pending".

Create File Entry

POST /agents/{agent_id}/knowledge/file

Uploads a document as multipart/form-data. Text is extracted server-side and then ingested in the background.

Form Fields

Field	Type	Required	Description
file	file	Yes	The document to upload
title	string	No	Optional title; derived from the filename when omitted

Allowed file types:

Type	MIME type
PDF	application/pdf
Word (.docx)	application/vnd.openxmlformats-officedocument.wordprocessingml.document
Plain text	text/plain
HTML	text/html
Markdown	text/markdown

The maximum upload size is 10 MB by default. Files above the limit, or with an unsupported MIME type, are rejected with 400 Bad Request.

curl -X POST https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/file \
  -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  -F "file=@handbook.pdf" \
  -F "title=Employee Handbook"

Response

201 Created - Returns the KnowledgeEntryResponse with status: "pending".

Get Entry

GET /agents/{agent_id}/knowledge/{entry_id}

Fetches a single entry. Use this to poll ingestion status after creation.

curl -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/{entry_id}

Response

200 OK - Returns the KnowledgeEntryResponse. A finished entry reads status: "ready"; a failed one reads status: "error" with the reason in error_message.

Delete Entry

DELETE /agents/{agent_id}/knowledge/{entry_id}

Permanently deletes an entry along with its embedded chunks and any stored file.

curl -X DELETE https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/{entry_id} \
  -H "X-API-Key: voc_a1b2c3d4e5f6..."

Response

204 No Content - No response body.

Reprocess Entry

POST /agents/{agent_id}/knowledge/{entry_id}/reprocess

Re-runs ingestion for an existing entry, resetting its status to pending. Use this to retry an entry that landed in error after a transient ingestion failure or after the tenant's embedding provider was fixed.

curl -X POST https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/{entry_id}/reprocess \
  -H "X-API-Key: voc_a1b2c3d4e5f6..."

Response

200 OK - Returns the KnowledgeEntryResponse with status: "pending". Poll the get endpoint until it settles.