Knowledge Bases

These endpoints let you list your organization’s knowledge bases, manage text items within each base, and run semantic searches (RAG) directly via API.

Base URL: https://api.squados.io/v1

Every request requires the Authorization: Bearer pk_... header. Requests with a body also need Content-Type: application/json. See Authentication for details on generating and using tokens.

---

Bases

GET /bases

Lists all knowledge bases in the organization.

Query parameters

Parameter	Type	Default	Description
limit	integer	50	Number of records per page. Maximum: 100.
offset	integer	0	Starting position for pagination.

curl https://api.squados.io/v1/bases \
  -H "Authorization: Bearer pk_your_key_here"

Response — 200 OK

{
  "bases": [
    {
      "id": "BASE_ID",
      "name": "Product Documentation",
      "description": "Base with manuals and FAQs",
      "item_count": 42,
      "created_at": "2025-03-10T14:22:00Z",
      "updated_at": "2025-06-01T09:45:00Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

---

GET /bases/{baseId}

Returns the details of a specific knowledge base.

Path parameters

Parameter	Type	Description
baseId	uuid	Knowledge base ID.

curl https://api.squados.io/v1/bases/BASE_ID \
  -H "Authorization: Bearer pk_your_key_here"

Response — 200 OK

{
  "id": "BASE_ID",
  "name": "Product Documentation",
  "description": "Base with manuals and FAQs",
  "item_count": 42,
  "created_at": "2025-03-10T14:22:00Z",
  "updated_at": "2025-06-01T09:45:00Z"
}

Errors: 404 if the base is not found.

---

Items

GET /bases/{baseId}/items

Lists the items in a knowledge base with optional status filtering.

Path parameters

Parameter	Type	Description
baseId	uuid	Knowledge base ID.

Query parameters

Parameter	Type	Default	Description
limit	integer	50	Number of records per page. Maximum: 100.
offset	integer	0	Starting position for pagination.
status	string	—	Filter by status: pending, processing, processed, or error.

curl "https://api.squados.io/v1/bases/BASE_ID/items?status=processed&limit=20" \
  -H "Authorization: Bearer pk_your_key_here"

Response — 200 OK

{
  "base_id": "BASE_ID",
  "items": [
    {
      "id": "ITEM_ID",
      "name": "Return Policy",
      "type": "text",
      "source": "text",
      "status": "processed",
      "chunk_count": 4,
      "token_count": 812,
      "content_preview": "Our return policy allows exchange or refund of any product within 30 days…",
      "created_at": "2025-05-20T11:00:00Z"
    }
  ],
  "total": 18,
  "limit": 20,
  "offset": 0
}

---

POST /bases/{baseId}/items

Inserts a new text item into the knowledge base.

Path parameters

Parameter	Type	Description
baseId	uuid	Knowledge base ID.

Request body

Field	Type	Required	Description
name	string	Yes	Item title. Minimum: 1 character.
content	string	Yes	Full text content. Maximum: 100,000 characters.

curl -X POST https://api.squados.io/v1/bases/BASE_ID/items \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Return Policy",
    "content": "Our policy allows exchange or refund of any product within 30 days of purchase..."
  }'

Response — 201 Created

{
  "id": "ITEM_ID",
  "base_id": "BASE_ID",
  "name": "Return Policy",
  "type": "text",
  "status": "pending",
  "created_at": "2025-06-08T12:00:00Z"
}

Note

Item processing is asynchronous. After insertion, the item starts with status: "pending" and goes through chunking, vectorization, and indexing in the background — steps triggered automatically by a database trigger. The full flow is pending → processing → processed. Track progress by calling GET /bases/{baseId}/items/{itemId} or listing items with GET /bases/{baseId}/items.

Errors: 400 if the body is invalid or content exceeds 100,000 characters; 404 if the base is not found.

---

GET /bases/{baseId}/items/{itemId}

Returns the full detail of an item, including its complete content.

Path parameters

Parameter	Type	Description
baseId	uuid	Knowledge base ID.
itemId	uuid	Item ID.

curl https://api.squados.io/v1/bases/BASE_ID/items/ITEM_ID \
  -H "Authorization: Bearer pk_your_key_here"

Response — 200 OK

{
  "id": "ITEM_ID",
  "base_id": "BASE_ID",
  "name": "Return Policy",
  "type": "text",
  "source": "text",
  "status": "processed",
  "chunk_count": 4,
  "token_count": 812,
  "content_preview": "Our return policy allows exchange or refund of any product within 30 days…",
  "content": "Our return policy allows exchange or refund of any product within 30 days of purchase. To request, log into your account and open a support ticket...",
  "created_at": "2025-05-20T11:00:00Z"
}

The content field holds the full text (up to 100,000 characters). If the item has not been processed yet, content is null.

Errors: 400 if baseId or itemId are not valid UUIDs; 404 if the item is not found.

---

PATCH /bases/{baseId}/items/{itemId}

Updates the name and/or content of a text item (source: "text").

Path parameters

Parameter	Type	Description
baseId	uuid	Knowledge base ID.
itemId	uuid	Item ID.

Request body — at least one field is required.

Field	Type	Required	Description
name	string	No	New item title.
content	string	No	New text content. Maximum: 100,000 characters.

curl -X PATCH https://api.squados.io/v1/bases/BASE_ID/items/ITEM_ID \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated text with the new return conditions..."
  }'

Response — 200 OK

Returns the updated BaseItemDetail. Note that status resets to "pending" because re-embedding is triggered automatically.

{
  "id": "ITEM_ID",
  "base_id": "BASE_ID",
  "name": "Return Policy",
  "type": "text",
  "source": "text",
  "status": "pending",
  "chunk_count": 0,
  "token_count": 0,
  "content_preview": null,
  "content": "Updated text with the new return conditions...",
  "created_at": "2025-05-20T11:00:00Z"
}

Caution

Items with source: "file" (PDFs and other files uploaded through the dashboard) return 409 Conflict — you cannot edit their content via API. To replace the content, delete the item and create a new one with source: "text". The endpoint also returns 409 if the item is currently in "processing" status.

---

DELETE /bases/{baseId}/items/{itemId}

Removes an item from the knowledge base.

Path parameters

Parameter	Type	Description
baseId	uuid	Knowledge base ID.
itemId	uuid	Item ID.

curl -X DELETE https://api.squados.io/v1/bases/BASE_ID/items/ITEM_ID \
  -H "Authorization: Bearer pk_your_key_here"

Response — 204 No Content

No body. Cleanup of the corresponding vectors in the vector store (Qdrant) is queued automatically after deletion.

Errors: 404 if the item is not found.

---

Semantic search (RAG)

POST /bases/{baseId}/query

Runs a semantic search directly against the knowledge base using embeddings. Useful for integrating RAG into external systems — receive the most relevant chunks for a question and use them in your own pipeline.

Path parameters

Parameter	Type	Description
baseId	uuid	Knowledge base ID.

Request body

Field	Type	Required	Description
query	string	Yes	Text to search semantically.
limit	integer	No	Maximum number of results. Default: 5. Maximum: 20.
min_score	number	No	Minimum similarity score (0 to 1). Default: 0.6.

Simple example:

curl -X POST https://api.squados.io/v1/bases/BASE_ID/query \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the return policy?"
  }'

Example with filters:

curl -X POST https://api.squados.io/v1/bases/BASE_ID/query \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the product prices?",
    "limit": 10,
    "min_score": 0.7
  }'

Response — 200 OK

{
  "query": "What is the return policy?",
  "results": [
    {
      "content": "Our policy allows exchange or refund of any product within 30 days of purchase...",
      "score": 0.92,
      "item_id": "ITEM_ID",
      "item_name": "Return Policy",
      "chunk_index": 0
    },
    {
      "content": "For products with manufacturing defects, the period is extended to 90 days...",
      "score": 0.81,
      "item_id": "ITEM_ID",
      "item_name": "Return Policy",
      "chunk_index": 1
    }
  ],
  "total_results": 2,
  "embedding_model": "text-embedding-3-small"
}

Each result returns the text chunk (content), its similarity score (0 to 1), the source item, and the chunk index within that item.

Errors: 400 if query is invalid or missing; 404 if the base is not found; 500 if RAG is not configured for the base.

---

For details on errors and HTTP status codes, see Errors.