Skip to content
Try for free
On this page

Knowledge bases

List knowledge bases

List active knowledge bases in a workspace with folder filtering, search, sorting, and cursor pagination. Use `scope=archived` to find knowledge bases available for restoration. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope: `api:read`.

GET/api/v2/knowledge

List active knowledge bases in a workspace with folder filtering, search, sorting, and cursor pagination. Use scope=archived to find knowledge bases available for restoration. Workspace folder trees exceeding 10,000 folders return 413.

OAuth scope: api:read.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:read.

Query parameters

workspaceIdstringRequired

Workspace whose knowledge bases should be listed.

minLength
1
maxLength
128
scopestring

Lifecycle scope: active or archived knowledge bases. Use Restore knowledge base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.

default
active
enum
["active","archived"]
folderPathstring

Restrict results to knowledge bases in this folder. Unknown folder paths contribute no matches.

maxLength
4096
searchstring

Case-insensitive substring match against the resource name.

minLength
1
maxLength
200
sortBystring

Field used to sort the result. Do not rely on case-insensitive ordering when sorting by name.

default
createdAt
enum
["name","createdAt","updatedAt"]
sortOrderstring

Sort direction.

default
asc
enum
["asc","desc"]
limitinteger

Maximum knowledge bases to return per page. Must be a whole number from 1 to 100. Defaults to 50.

default
50
minimum
1
maximum
100
cursorstring

Opaque cursor from the previous page. Send it back with the same sort and filters; only limit may change. Change anything else and pagination must restart without a cursor.

minLength
1

Responses

200

A page of knowledge bases.

object

A cursor-paginated page of knowledge bases.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject

A collection of documents indexed for vector and tag search.

15 fields
idstringRequired

Unique knowledge base identifier.

namestringRequired

Human-readable knowledge base name.

descriptionvalueRequired

Knowledge base description, or null when none is set.

Schema details

Any of

Option 1string
Option 2null
tokenCountnumberRequired

Total tokens across indexed documents.

embeddingModelstringRequired

Embedding model used to index documents.

embeddingDimensionnumberRequired

Dimensionality of the embedding vectors.

chunkingConfigobjectRequired

How documents in a knowledge base are split into chunks before embedding.

5 fields
maxSizenumberRequired

Maximum chunk size in tokens.

minSizenumberRequired

Minimum chunk size in characters.

overlapnumberRequired

Requested overlap in tokens between adjacent chunks.

strategystring

Chunking strategy applied during document processing.

enum
["auto","text","regex","recursive","sentence","token"]
strategyOptionsobject

Strategy-specific tuning options.

4 fields
patternstring

Regular expression used by the regex chunking strategy.

maxLength
500
separatorsarray

Ordered separators used to split content into chunks.

Schema details
Array itemstring
recipestring

Content-aware recipe used by the automatic chunking strategy.

enum
["plain","markdown","code"]
strictBoundariesboolean

Whether regex matches must form strict chunk boundaries.

Additional properties are not allowed.

Additional propertiesvalue

Additional forward-compatible chunking configuration property.

docCountnumber

Number of documents in the knowledge base.

connectorTypesarray

External connector types that have synced documents into the knowledge base.

Schema details
Array itemstring
createdAtstringRequired

ISO 8601 timestamp when the knowledge base was created.

format
date-time
updatedAtstringRequired

ISO 8601 timestamp when the knowledge base was last modified.

format
date-time
webUrlstringRequired

Canonical absolute URL for opening this resource in the Sim web application.

format
uri
ownerEmailstringRequired

Current email address of the knowledge base owner.

format
email
pattern
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
folderPathstringRequired

Canonical containing-folder path; / is the workspace root. Resolved against active folders only, so an archived knowledge base whose containing folder was archived with it reports /.

maxLength
4096
deletedAtvalueRequired

ISO 8601 archive timestamp, or null while active. Use List knowledge bases with scope=archived to find archived knowledge bases.

format
date-time
Schema details

Any of

Option 1string
format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Option 2null

Additional properties are not allowed.

nextCursorvalueRequired

Opaque cursor for the next page. Send it back as cursor; null means there are no more pages. Do not construct a cursor yourself.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit