Knowledge Bases

The Knowledge Bases API lets you inspect your organization’s bases, manage their items, and retrieve context for external applications. The public API does not create, rename, or delete the base itself: use SquadOS for those operations. Through the API, you inspect existing bases and create, read, update, or delete items.

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

Every request requires Authorization: Bearer pk_.... Requests with a body also require Content-Type: application/json. See Authentication.

Every endpoint is scoped to the token’s organization. An ID that belongs to another organization is treated as not found.

Bases

GET /bases

Lists the organization’s bases from newest to oldest.

Query	Type	Default	Rule
limit	integer	50	Maximum 100.
offset	integer	0	Starting position for the page.

curl "https://api.squados.io/v1/bases?limit=50&offset=0" \
  -H "Authorization: Bearer pk_your_key_here"

{
  "bases": [
    {
      "id": "BASE_ID",
      "name": "Product Documentation",
      "description": "Manuals and frequently asked questions",
      "item_count": 42,
      "created_at": "2026-08-15T14:22:00Z",
      "updated_at": "2026-08-31T09:45:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

description may be null. item_count is the base’s current item count.

GET /bases/{baseId}

Returns one base and its item count. description may be null.

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

Returns 400 when baseId is not a valid UUID and 404 when the base does not exist in the organization.

Items

An item goes through asynchronous processing. The expected states are:

Status	Meaning
pending	Waiting for processing.
processing	Extraction, splitting, and indexing are in progress.
processed	Available for retrieval.
error	Processing failed.

GET /bases/{baseId}/items

Lists the base’s items from newest to oldest.

Query	Type	Default	Rule
limit	integer	50	Maximum 100.
offset	integer	0	Starting position for the page.
status	string	—	Exact filter: 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"

{
  "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 policy accepts returns within 30 days...",
      "created_at": "2026-08-20T11:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

chunk_count, token_count, and content_preview may be null until processing produces a result.

POST /bases/{baseId}/items

Creates an item with source: "text".

Field	Type	Required	Rule
name	string	Yes	Must not be empty after trimming surrounding whitespace.
content	string	Yes	Must not be empty; 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": "We accept returns within 30 days of purchase."
  }'

The 201 Created response contains id, base_id, name, type, status, and created_at. The item starts with status: "pending" and asynchronously moves to processing and then processed or error.

Note

After creating or updating an item, poll GET /bases/{baseId}/items/{itemId} until it returns processed or error. Do not use elapsed time alone as a completion signal.

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

Returns the list fields plus base_id and content.

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

Text items preserve the submitted content in content, including before indexing finishes. For a file-sourced item, content may be null before extraction. chunk_count, token_count, and content_preview may also be null.

Returns 400 when either ID is not a valid UUID and 404 when the base or item does not exist in the organization.

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

Updates name, content, or both on an item with source: "text". At least one field is required; content remains limited to 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": "We accept returns within 45 days of purchase."
  }'

Every update — including a name-only update — resets status to pending and starts new processing. The 200 OK response returns the item detail. During this transition, chunk_count, token_count, and content_preview may still reflect the previous processing run; treat them as provisional until the new processed state.

Caution

Items with source: "file" cannot be updated through this endpoint and return 409 Conflict. An item currently in processing also returns 409; wait for its state to change before trying again.

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

Deletes the item and returns 204 No Content, with no body. The deletion queues asynchronous cleanup of vectors and chunk files in the same commit. The 204 confirms item deletion, not a specific deadline for internal cleanup.

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

Returns 400 for invalid IDs and 404 when the base or item does not exist in the organization.

Hybrid retrieval (RAG)

POST /bases/{baseId}/query

Retrieves base excerpts with the same engine used by agents: query expansion, dense and lexical (BM25) search, fusion, reranking, and deduplication. The query is restricted to the organization and exact base ID.

Field	Type	Required	Rule
query	string	Yes	Question or search text; an empty string is rejected.
limit	integer	No	Default 5; normalized to 1 through 20. Limits presentation without changing the outcome classification.
min_score	number	No	Deprecated and ignored. Accepted only for backward compatibility.

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 deadline?",
    "limit": 5
  }'

{
  "query": "What is the return deadline?",
  "results": [
    {
      "content": "We accept returns within 45 days of purchase.",
      "score": 0.92,
      "item_id": "ITEM_ID",
      "item_name": "Return policy",
      "chunk_index": 0
    }
  ],
  "total_results": 1,
  "embedding_model": "text-embedding-3-small",
  "outcome": "supported",
  "degraded": false
}

Interpreting the response

Field	Meaning
results	Final excerpts after reranking and limiting. Always [] for not_found.
total_results	Number of excerpts returned in results.
outcome	supported, uncertain, or not_found. Use this field to decide whether reliable context is available.
degraded	true when the organization used the legacy contingency engine. The response shape stays the same.
score	Reranker relevance from 0 to 1, rounded to four decimals. It is not cosine similarity. Compare only results from the same query and do not apply a fixed cutoff.
item_name	Source item name; may be null.
chunk_index	Excerpt index; may be an integer, string, or null.

Caution

Do not send min_score to filter results: the field is ignored. For safe automation, make decisions from outcome; not_found already comes with no results.

The endpoint returns 400 for invalid IDs or bodies, 404 for a missing base, 503 service_unavailable when a retrieval dependency is unavailable, and 500 for missing configuration or an unexpected failure.

See Errors for the API’s common failure format.