Knowledge Bases

Get Knowledge Bases

get

List all available knowledge bases for the specified flow.

Authorizations

HTTPBearer

Query parameters

cursorany ofOptional

Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.

Example: ZXhhbXBsZV9jdXJzb3I=

stringOptional

or

nullOptional

page_sizeinteger · min: 1 · max: 1000Optional

Number of items to be returned in the page.

Default: 50

directionstring · enumOptional

Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)

Default: nextPossible values:

Responses

200

Successful Response

application/json

Knowledge base response payload for public API endpoints.

knowledge_base_idstring · uuidRequired

connection_idany ofRequired

string · uuidOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

connection_source_idsstring[]Required

connection_provider_typeany ofOptional

stringOptional

or

nullOptional

is_emptybooleanOptionalDefault: true

total_sizeintegerOptional

Total size of all the files in the KB in bytes

Default: 0

total_filesintegerOptional

Total number of files in the KB

Default: 0

total_indexed_filesintegerOptional

Total number of indexed files in the KB

Default: 0

total_error_filesintegerOptional

Total number of error files in the KB

Default: 0

last_synced_atany ofOptional

Timestamp when the knowledge base was last successfully synced from its source

string · date-timeOptional

or

nullOptional

namestring · min: 1 · max: 2048OptionalDefault: Unnamed Knowledge Base

descriptionstring · max: 2048OptionalDefault: ""

org_idstringRequired

roleany ofOptional

string · enumOptional

Enumerates all the possible roles for a user in a knowledge base.

Attributes

• ADMIN: Admin permissions allow full control over the knowledge base, including deletion.
• EDITOR: Editor permissions allow the user to modify the knowledge base, but not delete it.
• VIEWER: Viewer permissions allow the user to view the knowledge base, but not modify it.

Possible values:

or

nullOptional

org_level_roleany ofOptional

string · enumOptional

Enumerates all the possible roles for a user in a knowledge base.

Attributes

• ADMIN: Admin permissions allow full control over the knowledge base, including deletion.
• EDITOR: Editor permissions allow the user to modify the knowledge base, but not delete it.
• VIEWER: Viewer permissions allow the user to view the knowledge base, but not modify it.

Possible values:

or

nullOptional

user_metadata_schemaany ofOptional

or

nullOptional

dataloader_metadata_schemaany ofOptional

or

nullOptional

422

Validation Error

application/json

get

/v1/knowledge-bases

HTTPcURLJavaScriptPython

GET /v1/knowledge-bases HTTP/1.1
Host: api.stack-ai.com
Accept: */*

[
  {
    "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
    "connection_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2026-04-03T09:35:29.592Z",
    "updated_at": "2026-04-03T09:35:29.592Z",
    "connection_source_ids": [
      "text"
    ],
    "website_sources": [
      {
        "source_type": "sitemap",
        "original_search_term": "text",
        "selected_resources": [
          "text"
        ]
      }
    ],
    "connection_provider_type": "text",
    "is_empty": true,
    "total_size": 0,
    "total_files": 0,
    "total_indexed_files": 0,
    "total_error_files": 0,
    "last_synced_at": "2026-04-03T09:35:29.592Z",
    "name": "Unnamed Knowledge Base",
    "description": "",
    "indexing_params": {
      "ocr": false,
      "embedding_params": {
        "embedding_model": "text",
        "api_key": "text"
      },
      "chunker_params": {
        "chunk_size": 1500,
        "chunk_overlap": 500,
        "chunker_type": "sentence"
      }
    },
    "org_id": "text",
    "role": "viewer",
    "org_level_role": "viewer",
    "user_metadata_schema": {
      "properties": {
        "^[^\\t\\n\\r\\f\\v]+$": {
          "type": "string",
          "description": "",
          "order": 0,
          "subtype": "plain"
        }
      }
    },
    "dataloader_metadata_schema": {
      "properties": {
        "^[^\\t\\n\\r\\f\\v]+$": {
          "type": "string",
          "description": "",
          "order": 0,
          "subtype": "plain"
        }
      }
    }
  }
]

Create Knowledge Base

post

Create a new knowledge base.

Authorizations

HTTPBearer

Body

application/json

Model for FastAPI endpoints.

connection_idany ofOptional

string · uuidOptional

or

nullOptional

connection_source_idsstring[]Optional

namestring · min: 1 · max: 2048OptionalDefault: Unnamed Knowledge Base

descriptionstring · max: 2048OptionalDefault: ""

org_level_roleany ofOptional

string · enumOptional

Enumerates all the possible roles for a user in a knowledge base.

Attributes

• ADMIN: Admin permissions allow full control over the knowledge base, including deletion.
• EDITOR: Editor permissions allow the user to modify the knowledge base, but not delete it.
• VIEWER: Viewer permissions allow the user to view the knowledge base, but not modify it.

Possible values:

or

nullOptional

Responses

201

Successful Response

application/json

422

Validation Error

application/json

post

/v1/knowledge-bases

HTTPcURLJavaScriptPython

POST /v1/knowledge-bases HTTP/1.1
Host: api.stack-ai.com
Content-Type: application/json
Accept: */*
Content-Length: 473

{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "connection_source_ids": [
    "text"
  ],
  "website_sources": [
    {
      "source_type": "sitemap",
      "original_search_term": "text",
      "selected_resources": [
        "text"
      ]
    }
  ],
  "name": "Unnamed Knowledge Base",
  "description": "",
  "indexing_params": {
    "ocr": false,
    "embedding_params": {
      "embedding_model": "openai.text-embedding-3-large",
      "api_key": "text"
    },
    "chunker_params": {
      "chunk_size": 1500,
      "chunk_overlap": 500,
      "chunker_type": "sentence"
    }
  },
  "org_level_role": "viewer"
}

{
  "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-04-03T09:35:29.592Z",
  "updated_at": "2026-04-03T09:35:29.592Z",
  "connection_source_ids": [
    "text"
  ],
  "website_sources": [
    {
      "source_type": "sitemap",
      "original_search_term": "text",
      "selected_resources": [
        "text"
      ]
    }
  ],
  "connection_provider_type": "text",
  "is_empty": true,
  "total_size": 0,
  "total_files": 0,
  "total_indexed_files": 0,
  "total_error_files": 0,
  "last_synced_at": "2026-04-03T09:35:29.592Z",
  "name": "Unnamed Knowledge Base",
  "description": "",
  "indexing_params": {
    "ocr": false,
    "embedding_params": {
      "embedding_model": "text",
      "api_key": "text"
    },
    "chunker_params": {
      "chunk_size": 1500,
      "chunk_overlap": 500,
      "chunker_type": "sentence"
    }
  },
  "org_id": "text",
  "role": "viewer",
  "org_level_role": "viewer",
  "user_metadata_schema": {
    "properties": {
      "^[^\\t\\n\\r\\f\\v]+$": {
        "type": "string",
        "description": "",
        "order": 0,
        "subtype": "plain"
      }
    }
  },
  "dataloader_metadata_schema": {
    "properties": {
      "^[^\\t\\n\\r\\f\\v]+$": {
        "type": "string",
        "description": "",
        "order": 0,
        "subtype": "plain"
      }
    }
  }
}

Get Knowledge Base By Id

get

Get a knowledge base by its ID in the current organization.

Authorizations

HTTPBearer

Path parameters

knowledge_base_idstring · uuidRequired

Responses

200

Successful Response

application/json

Knowledge base response payload for public API endpoints.

knowledge_base_idstring · uuidRequired

connection_idany ofRequired

string · uuidOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

connection_source_idsstring[]Required

connection_provider_typeany ofOptional

stringOptional

or

nullOptional

is_emptybooleanOptionalDefault: true

total_sizeintegerOptional

Total size of all the files in the KB in bytes

Default: 0

total_filesintegerOptional

Total number of files in the KB

Default: 0

total_indexed_filesintegerOptional

Total number of indexed files in the KB

Default: 0

total_error_filesintegerOptional

Total number of error files in the KB

Default: 0

last_synced_atany ofOptional

Timestamp when the knowledge base was last successfully synced from its source

string · date-timeOptional

or

nullOptional

namestring · min: 1 · max: 2048OptionalDefault: Unnamed Knowledge Base

descriptionstring · max: 2048OptionalDefault: ""

org_idstringRequired

roleany ofOptional

string · enumOptional

Enumerates all the possible roles for a user in a knowledge base.

Attributes

• ADMIN: Admin permissions allow full control over the knowledge base, including deletion.
• EDITOR: Editor permissions allow the user to modify the knowledge base, but not delete it.
• VIEWER: Viewer permissions allow the user to view the knowledge base, but not modify it.

Possible values:

or

nullOptional

org_level_roleany ofOptional

string · enumOptional

Enumerates all the possible roles for a user in a knowledge base.

Attributes

• ADMIN: Admin permissions allow full control over the knowledge base, including deletion.
• EDITOR: Editor permissions allow the user to modify the knowledge base, but not delete it.
• VIEWER: Viewer permissions allow the user to view the knowledge base, but not modify it.

Possible values:

or

nullOptional

user_metadata_schemaany ofOptional

or

nullOptional

dataloader_metadata_schemaany ofOptional

or

nullOptional

422

Validation Error

application/json

get

/v1/knowledge-bases/{knowledge_base_id}

HTTPcURLJavaScriptPython

GET /v1/knowledge-bases/{knowledge_base_id} HTTP/1.1
Host: api.stack-ai.com
Accept: */*

{
  "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-04-03T09:35:29.592Z",
  "updated_at": "2026-04-03T09:35:29.592Z",
  "connection_source_ids": [
    "text"
  ],
  "website_sources": [
    {
      "source_type": "sitemap",
      "original_search_term": "text",
      "selected_resources": [
        "text"
      ]
    }
  ],
  "connection_provider_type": "text",
  "is_empty": true,
  "total_size": 0,
  "total_files": 0,
  "total_indexed_files": 0,
  "total_error_files": 0,
  "last_synced_at": "2026-04-03T09:35:29.592Z",
  "name": "Unnamed Knowledge Base",
  "description": "",
  "indexing_params": {
    "ocr": false,
    "embedding_params": {
      "embedding_model": "text",
      "api_key": "text"
    },
    "chunker_params": {
      "chunk_size": 1500,
      "chunk_overlap": 500,
      "chunker_type": "sentence"
    }
  },
  "org_id": "text",
  "role": "viewer",
  "org_level_role": "viewer",
  "user_metadata_schema": {
    "properties": {
      "^[^\\t\\n\\r\\f\\v]+$": {
        "type": "string",
        "description": "",
        "order": 0,
        "subtype": "plain"
      }
    }
  },
  "dataloader_metadata_schema": {
    "properties": {
      "^[^\\t\\n\\r\\f\\v]+$": {
        "type": "string",
        "description": "",
        "order": 0,
        "subtype": "plain"
      }
    }
  }
}

Delete Kowledge Base

delete

Delete a knowledge base by its ID.

Authorizations

HTTPBearer

Path parameters

knowledge_base_idstring · uuidRequired

Responses

204

Successful Response

422

Validation Error

application/json

delete

/v1/knowledge-bases/{knowledge_base_id}

HTTPcURLJavaScriptPython

DELETE /v1/knowledge-bases/{knowledge_base_id} HTTP/1.1
Host: api.stack-ai.com
Accept: */*

No content

Update Knowledge Base

patch

Update a knowledge base.

Authorizations

HTTPBearer

Path parameters

knowledge_base_idstring · uuidRequired

Body

application/json

Request model to update a knowledge base.

connection_idany ofOptional

string · uuidOptional

or

nullOptional

connection_source_idsstring[]Optional

namestring · min: 1 · max: 2048OptionalDefault: Unnamed Knowledge Base

descriptionstring · max: 2048OptionalDefault: ""

indexing_paramsany ofOptional

or

nullOptional

org_level_roleany ofOptional

string · enumOptional

Enumerates all the possible roles for a user in a knowledge base.

Attributes

• ADMIN: Admin permissions allow full control over the knowledge base, including deletion.
• EDITOR: Editor permissions allow the user to modify the knowledge base, but not delete it.
• VIEWER: Viewer permissions allow the user to view the knowledge base, but not modify it.

Possible values:

or

nullOptional

Responses

200

Successful Response

application/json

Knowledge base response payload for public API endpoints.

knowledge_base_idstring · uuidRequired

connection_idany ofRequired

string · uuidOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

connection_source_idsstring[]Required

connection_provider_typeany ofOptional

stringOptional

or

nullOptional

is_emptybooleanOptionalDefault: true

total_sizeintegerOptional

Total size of all the files in the KB in bytes

Default: 0

total_filesintegerOptional

Total number of files in the KB

Default: 0

total_indexed_filesintegerOptional

Total number of indexed files in the KB

Default: 0

total_error_filesintegerOptional

Total number of error files in the KB

Default: 0

last_synced_atany ofOptional

Timestamp when the knowledge base was last successfully synced from its source

string · date-timeOptional

or

nullOptional

namestring · min: 1 · max: 2048OptionalDefault: Unnamed Knowledge Base

descriptionstring · max: 2048OptionalDefault: ""

org_idstringRequired

roleany ofOptional

string · enumOptional

Enumerates all the possible roles for a user in a knowledge base.

Attributes

• ADMIN: Admin permissions allow full control over the knowledge base, including deletion.
• EDITOR: Editor permissions allow the user to modify the knowledge base, but not delete it.
• VIEWER: Viewer permissions allow the user to view the knowledge base, but not modify it.

Possible values:

or

nullOptional

org_level_roleany ofOptional

string · enumOptional

Enumerates all the possible roles for a user in a knowledge base.

Attributes

• ADMIN: Admin permissions allow full control over the knowledge base, including deletion.
• EDITOR: Editor permissions allow the user to modify the knowledge base, but not delete it.
• VIEWER: Viewer permissions allow the user to view the knowledge base, but not modify it.

Possible values:

or

nullOptional

user_metadata_schemaany ofOptional

or

nullOptional

dataloader_metadata_schemaany ofOptional

or

nullOptional

422

Validation Error

application/json

patch

/v1/knowledge-bases/{knowledge_base_id}

HTTPcURLJavaScriptPython

PATCH /v1/knowledge-bases/{knowledge_base_id} HTTP/1.1
Host: api.stack-ai.com
Content-Type: application/json
Accept: */*
Content-Length: 473

{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "connection_source_ids": [
    "text"
  ],
  "website_sources": [
    {
      "source_type": "sitemap",
      "original_search_term": "text",
      "selected_resources": [
        "text"
      ]
    }
  ],
  "name": "Unnamed Knowledge Base",
  "description": "",
  "indexing_params": {
    "ocr": false,
    "embedding_params": {
      "embedding_model": "openai.text-embedding-3-large",
      "api_key": "text"
    },
    "chunker_params": {
      "chunk_size": 1500,
      "chunk_overlap": 500,
      "chunker_type": "sentence"
    }
  },
  "org_level_role": "viewer"
}

{
  "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-04-03T09:35:29.592Z",
  "updated_at": "2026-04-03T09:35:29.592Z",
  "connection_source_ids": [
    "text"
  ],
  "website_sources": [
    {
      "source_type": "sitemap",
      "original_search_term": "text",
      "selected_resources": [
        "text"
      ]
    }
  ],
  "connection_provider_type": "text",
  "is_empty": true,
  "total_size": 0,
  "total_files": 0,
  "total_indexed_files": 0,
  "total_error_files": 0,
  "last_synced_at": "2026-04-03T09:35:29.592Z",
  "name": "Unnamed Knowledge Base",
  "description": "",
  "indexing_params": {
    "ocr": false,
    "embedding_params": {
      "embedding_model": "text",
      "api_key": "text"
    },
    "chunker_params": {
      "chunk_size": 1500,
      "chunk_overlap": 500,
      "chunker_type": "sentence"
    }
  },
  "org_id": "text",
  "role": "viewer",
  "org_level_role": "viewer",
  "user_metadata_schema": {
    "properties": {
      "^[^\\t\\n\\r\\f\\v]+$": {
        "type": "string",
        "description": "",
        "order": 0,
        "subtype": "plain"
      }
    }
  },
  "dataloader_metadata_schema": {
    "properties": {
      "^[^\\t\\n\\r\\f\\v]+$": {
        "type": "string",
        "description": "",
        "order": 0,
        "subtype": "plain"
      }
    }
  }
}

List Resources

get

List files in the knowledge base with optional cursor pagination.

Authorizations

HTTPBearer

Path parameters

knowledge_base_idstring · uuidRequired

Query parameters

cursorany ofOptional

Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.

Example: NTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAw

stringOptional

or

nullOptional

page_sizeinteger · min: 1 · max: 100Optional

Number of items to be returned in the page.

Default: 50

directionstring · enumOptional

Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)

Default: nextPossible values:

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

get

/v1/knowledge-bases/{knowledge_base_id}/resources

HTTPcURLJavaScriptPython

GET /v1/knowledge-bases/{knowledge_base_id}/resources HTTP/1.1
Host: api.stack-ai.com
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Create Resource

post

Upload a file directly to a knowledge base and start indexing.

This endpoint allows API users to upload files directly without needing to use presigned URLs. The file is uploaded to storage and indexing is started automatically.

Authorizations

HTTPBearer

Path parameters

knowledge_base_idstring · uuidRequired

Body

multipart/form-data

filestring · binaryRequired

The file to upload to the knowledge base

Responses

202

Successful Response

application/json

422

Validation Error

application/json

post

/v1/knowledge-bases/{knowledge_base_id}/resources

HTTPcURLJavaScriptPython

POST /v1/knowledge-bases/{knowledge_base_id}/resources HTTP/1.1
Host: api.stack-ai.com
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}

{
  "message": "text"
}

Get Resource By Id

get

Get one file resource by ID from the knowledge base.

Authorizations

HTTPBearer

Path parameters

knowledge_base_idstring · uuidRequired

resource_idstring · uuidRequired

Responses

200

Successful Response

application/json

API response model for a KB file (without signed download URL).

knowledge_base_idstring · uuidRequired

created_atstring · date-timeRequired

modified_atstring · date-timeRequired

indexed_atany ofOptional

string · date-timeOptional

or

nullOptional

resource_idany ofRequired

string · uuidOptional

or

nullOptional

resource_pathstring · min: 1Required

dataloader_metadataobject · Dataloader MetadataOptional

user_metadataobject · User MetadataOptional

content_hashstring · min: 1Required

content_mimestring · min: 1Required

sizeintegerRequired

statusstring · enumRequired

Enumerates all the possible status of a file in the Stack Virtual File System.

Possible values:

422

Validation Error

application/json

get

/v1/knowledge-bases/{knowledge_base_id}/resources/{resource_id}

HTTPcURLJavaScriptPython

GET /v1/knowledge-bases/{knowledge_base_id}/resources/{resource_id} HTTP/1.1
Host: api.stack-ai.com
Accept: */*

{
  "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-04-03T09:35:29.592Z",
  "modified_at": "2026-04-03T09:35:29.592Z",
  "indexed_at": "2026-04-03T09:35:29.592Z",
  "resource_id": "123e4567-e89b-12d3-a456-426614174000",
  "resource_path": "text",
  "dataloader_metadata": {
    "^[^\\t\\n\\r\\f\\v]+$": null
  },
  "user_metadata": {
    "^[^\\t\\n\\r\\f\\v]+$": null
  },
  "content_hash": "text",
  "content_mime": "text",
  "size": 1,
  "status": "resource"
}

Delete Resource By Id

delete

Delete a file resource by inode ID.

Authorizations

HTTPBearer

Path parameters

knowledge_base_idstring · uuidRequired

resource_idstring · uuidRequired

Responses

204

Successful Response

422

Validation Error

application/json

delete

/v1/knowledge-bases/{knowledge_base_id}/resources/{resource_id}

HTTPcURLJavaScriptPython

DELETE /v1/knowledge-bases/{knowledge_base_id}/resources/{resource_id} HTTP/1.1
Host: api.stack-ai.com
Accept: */*

No content

Synchronize Knowledge Base

post

Synchronize the knowledge base.

Authorizations

HTTPBearer

Path parameters

knowledge_base_idstring · uuidRequired

Responses

202

Successful Response

application/json

422

Validation Error

application/json

post

/v1/knowledge-bases/{knowledge_base_id}/sync

HTTPcURLJavaScriptPython

POST /v1/knowledge-bases/{knowledge_base_id}/sync HTTP/1.1
Host: api.stack-ai.com
Accept: */*

{
  "message": "text",
  "status": "accepted"
}