Knowledge base API reference

Use the knowledge base API to create and manage knowledge bases, link files from Celigo Storage, and check indexing status and health. This reference is for developers who automate knowledge bases through the API. You attach a knowledge base to an AI agent through the agent's import, using the imports API. For setup instructions and examples, see Create and manage knowledge bases for AI agents.

Base URL

Each environment has its own knowledge bases. A request reads and changes the knowledge bases of its token's environment.

Authentication

Send an API token with Full access as a bearer token:

Authorization: Bearer <token>

A request without a token gets 401 access_token_required. A request with any other token gets 401 access_restricted. Requests that send a body must use Content-Type: application/json, or they get 415 invalid_content_type.

Endpoints

Knowledge base

Unknown fields in a request body are ignored.

List knowledge bases

GET /v1/knowledgebases

The response is 200 OK with an array of knowledge bases. When there are more, the Link header holds the next and previous pages.

Create a knowledge base

POST /v1/knowledgebases

The body takes name, description, contentExpiration, contentAge, and _integrationId. The response is 201 Created with the knowledge base. Send contentExpiration with every create: a body that leaves out both contentExpiration and contentAge gets 422 missing_required_field, because the default, warn, needs a contentAge.

Update a knowledge base

PATCH /v1/knowledgebases/{_id}
PUT /v1/knowledgebases/{_id}

PATCH changes only the fields in the body, and null clears an optional field. PUT replaces every field: a field it leaves out is cleared, contentExpiration returns to warn, and leaving out _integrationId removes the registration. Use PATCH for routine changes. Both return 200 OK with the knowledge base, and the change applies at each agent's next search.

Delete a knowledge base

DELETE /v1/knowledgebases/{_id}

The response is 204 No Content. Deleting removes the knowledge base's index and can't be undone. Its files stay in Celigo Storage.

• 409 knowledge_base_in_use: AI agents still list the knowledge base. The message names up to 10 of them. Detach it and try again.
• 502 knowledge_base_delete_failed: Celigo couldn't remove the index, and the knowledge base wasn't deleted. Try again later.

List a knowledge base's files

GET /v1/knowledgebases/{_id}/files

The response is 200 OK with an array of files:

Link a file

POST /v1/knowledgebases/{_id}/files/link

{ "_fileId": "683b2a0e1c3d5f001a9e8b01", "filename": "returns-policy-2026.pdf" }

Both fields are required. _fileId is the file's Celigo Storage ID, and filename is up to 256 characters. Your token must be able to open the file in Celigo Storage. The response is 202 Accepted, and indexing runs in the background:

{
  "_id": "6a1f0c9d9b0c4d001e8f7b10",
  "_fileId": "683b2a0e1c3d5f001a9e8b01",
  "filename": "returns-policy-2026.pdf",
  "status": "queued",
  "_runId": "6a1f0c9d9b0c4d001e8f7b11"
}

Remove a file

DELETE /v1/knowledgebases/{_id}/files/{_kbFileId}

{_kbFileId} is the file's _id within the knowledge base, not its Celigo Storage ID. The response is 202 Accepted, and the file is removed from the index in the background. The file stays in Celigo Storage. A file that isn't in the knowledge base gets 404 knowledge_base_file_not_found.

Knowledge base health

GET /v1/knowledgebases/{_id}/health
GET /v1/knowledgebases/health?ids=<id>,<id>

The second form takes up to 50 comma-separated IDs and returns an array. IDs that don't exist, or that your token can't see, are left out.

Attach knowledge bases to an AI agent

An AI agent import lists its knowledge bases in aiAgent.attachedKnowledgeBaseIds, an array of up to 50 distinct knowledge base IDs. Save it with the imports API (/v1/imports):

• Use PATCH with replace on /aiAgent/attachedKnowledgeBaseIds, sending the whole list. An empty list detaches every knowledge base. add at /- and remove at an array index aren't supported.
• With PUT, include the list in the aiAgent object. A PUT that leaves it out can clear it.
• Each knowledge base the save adds is checked. It must exist in the agent's environment, and the token must be able to see it. Knowledge bases already on the agent aren't checked again, so an agent whose knowledge base was deleted can still be saved, and you can detach it.

A clone within the same environment keeps the list. A clone into another environment, and a template or integration app install, starts with an empty list.

Errors

Error responses have this shape:

{
  "errors": [
    {
      "field": "name",
      "code": "name_already_taken",
      "message": "A knowledge base named 'Returns policy' already exists in this account. Knowledge base names are case insensitive.",
      "source": "resource"
    }
  ]
}

field is present on validation errors.

Related articles

• Ground AI agents in your documents with knowledge bases
• Create and manage API and Personal Access tokens
• Manage Celigo Storage files with the Celigo APIs connector