Knowledge bases - Synthesys Docs

Create and manage knowledge bases, and read the entries your agents answer from.

A knowledge base is a named collection of entries that an agent can draw on during a call. You can create, rename and delete knowledge bases here. Entries are read-only through this API.

Endpoint	Request
List knowledge bases	GET`/v1/knowledge-bases`
Get a knowledge base	GET`/v1/knowledge-bases/:id`
Create a knowledge base	POST`/v1/knowledge-bases`
Update a knowledge base	PATCH`/v1/knowledge-bases/:id`
Delete a knowledge base	DEL`/v1/knowledge-bases/:id`
List entries	GET`/v1/knowledge-bases/:id/entries`

The knowledge base object

Fields use camelCase. Optional fields are left out of the response when they have no value.

Attributes

idstringrequired

The knowledge base's UUID.

namestringrequired

The name. Each name is unique within your account.

descriptionstring

The description, if one is set.

entryCountintegerrequired

The number of entries. List and get return the real count. Create and update always return 0.

createdAtstringrequired

ISO 8601 creation time.

updatedAtstringrequired

ISO 8601 time of the last change.

The entry object

Attributes

idstringrequired

The entry's UUID.

knowledgeBaseIdstringrequired

The UUID of the knowledge base it belongs to.

questionstring

The question, if the entry has one.

answerstringrequired

The entry's answer or stored text.

categorystring

The category, if one is set.

priorityintegerrequired

The entry's priority. Defaults to 5.

entryTypestringrequired

One of qa_pair, document or scraped_url.

fileNamestring

The file name, for entries created from a file.

fileSizeinteger

The file size, for entries created from a file.

mimeTypestring

The file's MIME type, for entries created from a file.

createdAtstringrequired

ISO 8601 creation time.

updatedAtstringrequired

ISO 8601 time of the last change.

List knowledge bases

GET/v1/knowledge-basesread key

Returns your knowledge bases, sorted by name.

Query parameters

limitintegerdefault 50

Maximum results, from 1 to 100.

offsetintegerdefault 0

Number of results to skip, up to 1,000,000.

searchstring

Case-insensitive match on part of the name, up to 200 characters. A value made only of * returns 400.

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

A limit or offset outside the allowed range returns 400.

Request

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

Response

{
  "success": true,
  "data": [
    {
      "id": "3f2a9c1e-7b4d-4e8a-9f10-2c6d8e1a5b70",
      "name": "Support FAQ",
      "description": "Answers to common support questions",
      "createdAt": "2026-09-01T10:00:00+00:00",
      "updatedAt": "2026-09-14T08:30:00+00:00",
      "entryCount": 42
    }
  ],
  "pagination": { "total": 1, "limit": 10, "offset": 0 }
}

Get a knowledge base

GET/v1/knowledge-bases/:idread key

Returns one knowledge base with its entry count.

Returns 404 if the knowledge base doesn't exist on your account. An ID that isn't a valid UUID returns 400.

Request

curl https://backend.synthesys.app/api/v1/knowledge-bases/3f2a9c1e-7b4d-4e8a-9f10-2c6d8e1a5b70 \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "id": "3f2a9c1e-7b4d-4e8a-9f10-2c6d8e1a5b70",
    "name": "Support FAQ",
    "description": "Answers to common support questions",
    "createdAt": "2026-09-01T10:00:00+00:00",
    "updatedAt": "2026-09-14T08:30:00+00:00",
    "entryCount": 42
  }
}

Creates an empty knowledge base and returns it with status 201. The body takes only the fields below. Other fields, such as agent_id, are ignored, so link a knowledge base to an agent in the dashboard.

Body parameters

namestringrequired

The name, from 1 to 255 characters. It must be unique within your account.

descriptionstring

The description, up to 1000 characters.

Errors:

400: name is missing or empty, or a value is over its length limit. details.issues names the field.
409: a knowledge base with this name already exists.

Request

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 to common support questions"}'

Response

{
  "success": true,
  "data": {
    "id": "3f2a9c1e-7b4d-4e8a-9f10-2c6d8e1a5b70",
    "name": "Support FAQ",
    "description": "Answers to common support questions",
    "createdAt": "2026-10-01T10:00:00+00:00",
    "updatedAt": "2026-10-01T10:00:00+00:00",
    "entryCount": 0
  }
}

Update a knowledge base

PATCH/v1/knowledge-bases/:idwrite key

Changes the name or description. Send at least one field.

Body parameters

namestring

The new name, from 1 to 255 characters.

descriptionstring

The new description, up to 1000 characters.

Errors:

400: the body is empty, name is empty, or a value is over its length limit.
404: the knowledge base doesn't exist on your account.
409: a knowledge base with this name already exists.

Request

curl -X PATCH https://backend.synthesys.app/api/v1/knowledge-bases/3f2a9c1e-7b4d-4e8a-9f10-2c6d8e1a5b70 \
  -H "SYNTH_API_KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer support FAQ"}'

Response

{
  "success": true,
  "data": {
    "id": "3f2a9c1e-7b4d-4e8a-9f10-2c6d8e1a5b70",
    "name": "Customer support FAQ",
    "description": "Answers to common support questions",
    "createdAt": "2026-09-01T10:00:00+00:00",
    "updatedAt": "2026-10-01T10:00:00+00:00",
    "entryCount": 0
  }
}

Delete a knowledge base

DEL/v1/knowledge-bases/:iddelete key

Deletes the knowledge base and all its entries, and unlinks it from any agents that use it.

Returns 404 if the knowledge base doesn't exist on your account. An ID that isn't a valid UUID returns 400.

Request

curl -X DELETE https://backend.synthesys.app/api/v1/knowledge-bases/3f2a9c1e-7b4d-4e8a-9f10-2c6d8e1a5b70 \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

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

List entries

GET/v1/knowledge-bases/:id/entriesread key

Returns the entries in a knowledge base. Here, pagination.total is the full number of matching entries.

Query parameters

limitintegerdefault 50

Maximum results, from 1 to 100.

offsetintegerdefault 0

Number of results to skip.

searchstring

Case-insensitive match on part of the question or answer, from 2 to 200 characters. A value made only of * returns 400.

categorystring

Return only entries with this exact category, up to 100 characters.

entry_typestring

Return only entries of this type: qa_pair, document or scraped_url.

Errors:

400: entry_type, limit, offset or search is invalid.
404: the knowledge base doesn't exist on your account.

Request

curl "https://backend.synthesys.app/api/v1/knowledge-bases/3f2a9c1e-7b4d-4e8a-9f10-2c6d8e1a5b70/entries?entry_type=qa_pair&limit=20" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "knowledgeBaseId": "3f2a9c1e-7b4d-4e8a-9f10-2c6d8e1a5b70",
      "question": "What are your opening hours?",
      "answer": "We are open from 9am to 5pm, Monday to Friday.",
      "category": "general",
      "priority": 5,
      "entryType": "qa_pair",
      "createdAt": "2026-09-01T10:05:00+00:00",
      "updatedAt": "2026-09-01T10:05:00+00:00"
    }
  ],
  "pagination": { "total": 1, "limit": 20, "offset": 0 }
}