DigitalOcean API (unofficial showcase)
POST/v2/gen-ai/knowledge_bases

Create a knowledge base

Creates a knowledge base in a specified region and project, optionally using an existing database. Configure its name, embedding model, size, tags, VPC, and retrieval reranking with the corresponding fields. You can attach data sources during creation or add them later.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

10 body fields

Optional knowledge base configuration, including deployment details, retrieval settings, tags, and data sources.

database_idstringoptional
Identifier of the DigitalOcean OpenSearch database this knowledge base will use, optional. If not provided, we create a new database for the knowledge base in the same region as the knowledge base.
datasourcesarray<object>optional
Optional data sources to attach at creation. Omit or use an empty list to create the knowledge base without sources, then add sources (with chunking strategy and sizes) using [Add a Data Source to a Knowledge Base](#operation/create_knowledge_base_data_source). When provided, see [Organize Data Sources](https://docs.digitalocean.com/products/inference/how-to/create-manage-agent-knowledge-bases/#add-data-sources) for best practices.
embedding_model_uuidstringoptional
Identifier for the [embedding model](https://docs.digitalocean.com/products/genai-platform/details/models/#embedding-models).
namestringoptional
Name of the knowledge base.
project_idstringoptional
Identifier of the DigitalOcean project this knowledge base will belong to.
regionstringoptional
The datacenter region to deploy the knowledge base in.
reranking_configobjectoptional
Configuration for cross-encoder reranking during retrieval.
sizestringoptional
OpenSearch plan size: OPEN_SEARCH_PLAN_SIZE_UNSPECIFIED, OPEN_SEARCH_PLAN_SIZE_SMALL, OPEN_SEARCH_PLAN_SIZE_MEDIUM, OPEN_SEARCH_PLAN_SIZE_LARGE, or OPEN_SEARCH_PLAN_SIZE_EXTRA_LARGE. Defaults to OPEN_SEARCH_PLAN_SIZE_UNSPECIFIED when omitted.
Allowed:OPEN_SEARCH_PLAN_SIZE_UNSPECIFIEDOPEN_SEARCH_PLAN_SIZE_SMALLOPEN_SEARCH_PLAN_SIZE_MEDIUMOPEN_SEARCH_PLAN_SIZE_LARGEOPEN_SEARCH_PLAN_SIZE_EXTRA_LARGEDefault:OPEN_SEARCH_PLAN_SIZE_UNSPECIFIED
tagsarray<string>optional
Tags to organize your knowledge base.
vpc_uuidstringoptional
The VPC to deploy the knowledge base database in

6 status codes
200Returns information about the created knowledge base.
knowledge_baseobjectoptional
Knowledgebase Description
401Returned when authentication fails because the credentials are invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404Returned when a referenced resource is not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Returned when the API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Returned when a server error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultReturned when an unexpected error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned when authentication credentials are invalid, and a 404 is returned when a referenced resource cannot be found. A 429 is returned when the API rate limit is exceeded, and a 500 indicates a server error. size and datasources[].chunking_algorithm must use one of their documented enum values when supplied.