Manage knowledge bases - Synthesys Docs

Create, update, list and delete knowledge bases, and read their entries, through the API.

A knowledge base holds the questions, answers, documents and scraped pages an agent can draw on during a call. The API manages the knowledge base itself and gives read access to its entries.

Task	Route	Permission
Create a knowledge base	`POST /v1/knowledge-bases`	`write`
List knowledge bases	`GET /v1/knowledge-bases`	`read`
Get a knowledge base	`GET /v1/knowledge-bases/:id`	`read`
Update a name or description	`PATCH /v1/knowledge-bases/:id`	`write`
Delete a knowledge base	`DELETE /v1/knowledge-bases/:id`	`delete`
Read entries	`GET /v1/knowledge-bases/:id/entries`	`read`

See the knowledge bases reference for every parameter.

Create a knowledge base

name is required, up to 255 characters, and must be unique on your account. description is optional, up to 1,000 characters.

curl -X POST https://backend.synthesys.app/api/v1/knowledge-bases \
  -H "SYNTH_API_KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support FAQ", "description": "Answers for the support line"}'

A successful request returns 201. Knowledge base fields use camelCase.

JSON

{
  "success": true,
  "data": {
    "id": "3f2b8c1e-5a47-4d09-8e16-7c9a0b1d2e34",
    "name": "Support FAQ",
    "description": "Answers for the support line",
    "createdAt": "2026-10-31T09:00:00.000Z",
    "updatedAt": "2026-10-31T09:00:00.000Z",
    "entryCount": 0
  }
}

A duplicate name returns 409 with the code CONFLICT. The body takes only name and description, so other fields such as agent_id are ignored.

Update a knowledge base

Send name, description or both. An empty body returns 400, and a name that's already in use returns 409.

curl -X PATCH https://backend.synthesys.app/api/v1/knowledge-bases/YOUR_KNOWLEDGE_BASE_ID \
  -H "SYNTH_API_KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Answers for support and billing"}'

List knowledge bases

Results are sorted by name. search filters on part of the name. limit goes up to 100, and offset skips results.

pagination.total is the true number of matching knowledge bases.

curl "https://backend.synthesys.app/api/v1/knowledge-bases?search=support&limit=20" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

To see which knowledge base an agent uses, read knowledgeBaseId from GET /v1/agents/:id.

Read entries

Query parameters

limitintegerdefault 50

Maximum results, up to 100.

offsetintegerdefault 0

Number of results to skip.

searchstring

Matches part of the question or answer, ignoring case. It must be from 2 to 200 characters, and a value made only of * returns 400.

categorystring

Exact category match.

entry_typestring

qa_pair, document or scraped_url.

Entries have no guaranteed order. pagination.total on this route is the real count of matching entries, so you can use it to page through them. An ID that isn't on your account returns 404.

This example exports every question and answer from a knowledge base.

curl "https://backend.synthesys.app/api/v1/knowledge-bases/YOUR_KNOWLEDGE_BASE_ID/entries?entry_type=qa_pair&limit=100" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

JSON

{
  "success": true,
  "data": [
    {
      "id": "a1c7d9e2-4b36-4f08-9d21-6e5f4a3b2c10",
      "knowledgeBaseId": "3f2b8c1e-5a47-4d09-8e16-7c9a0b1d2e34",
      "question": "What are your opening hours?",
      "answer": "We're open 9am to 5pm, Monday to Friday.",
      "category": "General",
      "priority": 5,
      "entryType": "qa_pair",
      "createdAt": "2026-10-31T09:05:00.000Z",
      "updatedAt": "2026-10-31T09:05:00.000Z"
    }
  ],
  "pagination": { "total": 1, "limit": 100, "offset": 0 }
}

Fields with no value are left out of the response. document entries can also include fileName, fileSize and mimeType.

Delete a knowledge base

This removes the knowledge base and its entries, and unlinks it from any agents using it. The key needs delete permission.

curl -X DELETE https://backend.synthesys.app/api/v1/knowledge-bases/YOUR_KNOWLEDGE_BASE_ID \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

JSON

{ "success": true, "message": "Knowledge base deleted successfully" }

You get the same response for an ID that doesn't exist on your account, so a success doesn't prove something was deleted.