Compozy Symbol
ALPHA
DocsInstallGetting StartedFeaturesPricing
CoreCLI ReferenceSchema DefinitionAPI Reference

Knowledge Bases

Manage knowledge bases, ingestion jobs, and retrieval queries via the REST API.

Knowledge base management operations

List knowledge bases

List knowledge bases with cursor-based pagination.

GET
/knowledge-bases

Query Parameters

project?string

Project override

limit?integer

Page size (max 500)

cursor?string

Opaque pagination cursor

Response Body

curl -X GET "https://loading/api/v0/knowledge-bases?project=string&limit=0&cursor=string"
{
  "data": {
    "knowledge_bases": [
      {
        "property1": null,
        "property2": null
      }
    ],
    "page": {
      "limit": 50,
      "next_cursor": "v2:after:tool-001",
      "prev_cursor": "v2:before:tool-000",
      "total": 2
    }
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Get knowledge base

Retrieve a knowledge base by ID.

GET
/knowledge-bases/{kb_id}

Path Parameters

kb_idstring

Knowledge base ID

Query Parameters

project?string

Project override

Response Body

curl -X GET "https://loading/api/v0/knowledge-bases/string?project=string"
{
  "data": {
    "knowledge_base": {
      "property1": null,
      "property2": null
    }
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Create or update knowledge base

Create a knowledge base when absent or update an existing one using strong ETag concurrency.

PUT
/knowledge-bases/{kb_id}

Path Parameters

kb_idstring

Knowledge base ID

Query Parameters

project?string

Project override

Header Parameters

If-Match?string

Strong ETag for optimistic concurrency

Request Body

Knowledge base definition

Empty Object

Response Body

curl -X PUT "https://loading/api/v0/knowledge-bases/string?project=string" \
  -H "If-Match: string" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "data": {
    "knowledge_base": {
      "property1": null,
      "property2": null
    }
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": {
    "knowledge_base": {
      "property1": null,
      "property2": null
    }
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Delete knowledge base

Delete a knowledge base and remove persisted vectors.

DELETE
/knowledge-bases/{kb_id}

Path Parameters

kb_idstring

Knowledge base ID

Query Parameters

project?string

Project override

Header Parameters

If-Match?string

Strong ETag for optimistic concurrency

Response Body

curl -X DELETE "https://loading/api/v0/knowledge-bases/string?project=string" \
  -H "If-Match: string"
"string"
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Ingest knowledge base

Trigger ingestion for configured sources using the requested strategy.

POST
/knowledge-bases/{kb_id}/ingest

Path Parameters

kb_idstring

Knowledge base ID

Query Parameters

project?string

Project override

Request Body

Ingestion request

strategy?string

Response Body

curl -X POST "https://loading/api/v0/knowledge-bases/string/ingest?project=string" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "data": {
    "binding_id": "binding-123",
    "chunks": 16,
    "documents": 2,
    "knowledge_base_id": "support",
    "persisted": 16
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Query knowledge base

Execute a dense similarity query against a knowledge base.

POST
/knowledge-bases/{kb_id}/query

Path Parameters

kb_idstring

Knowledge base ID

Query Parameters

project?string

Project override

Request Body

Query request

filters?object

Empty Object

min_score?number
querystring
top_k?integer

Response Body

curl -X POST "https://loading/api/v0/knowledge-bases/string/query?project=string" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I reset my password?"
  }'
{
  "data": {
    "matches": [
      {
        "binding_id": "binding-123",
        "content": "Reset your password by visiting the account settings page.",
        "metadata": {
          "property1": null,
          "property2": null
        },
        "score": 0.83,
        "token_estimate": 120
      }
    ]
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Memories

Memory configuration endpoints

Schedules

Schedule management operations