GradientAI Platform

Generated on 3 Apr 2026

Copy page as Markdown View page as Markdown

The API lets you build GPU-powered AI agents with pre-built or custom foundation models, function and agent routes, and RAG pipelines with knowledge bases.

Base URL https://api.digitalocean.com

Endpoints

GET List Agents POST Create an Agent GET List Agent API Keys POST Create an Agent API Key PUT Update API Key for an Agent DELETE Delete API Key for an Agent PUT Regenerate API Key for an Agent POST Add Function Route to an Agent PUT Update Function Route for an Agent DELETE Delete Function Route for an Agent POST Attach Guardrails to an Agent DELETE Detach a Guardrail from an Agent POST Attach Knowledge Bases to an Agent POST Attach Knowledge Base to an Agent DELETE Detach Knowledge Base from an Agent POST Add Agent Route to an Agent PUT Update Agent Route for an Agent DELETE Delete Agent Route for an Agent GET Retrieve an Existing Agent PUT Update an Agent DELETE Delete an Agent GET View Agent Routes PUT Update Agent Status GET Get Agent Usage GET List Agent Versions PUT Rollback to Agent Version GET List Anthropic API Keys POST Create Anthropic API Key GET Get Anthropic API Key PUT Update Anthropic API Key DELETE Delete Anthropic API Key GET List agents by Anthropic key POST Create Evaluation Dataset POST Create Presigned URLs for Evaluation Dataset File Upload GET List Evaluation Metrics POST Run an Evaluation Test Case GET Retrieve Information About an Existing Evaluation Run GET Retrieve Results of an Evaluation Run GET Retrieve Results of an Evaluation Run Prompt GET List Evaluation Test Cases POST Create Evaluation Test Case. GET List Evaluation Runs by Test Case GET Retrieve Information About an Existing Evaluation Test Case PUT Update an Evaluation Test Case. GET List Indexing Jobs for a Knowledge Base POST Start Indexing Job for a Knowledge Base GET List Data Sources for Indexing Job for a Knowledge Base GET Get Signed URL for Indexing Job Details GET Retrieve Status of Indexing Job for a Knowledge Base PUT Cancel Indexing Job for a Knowledge Base GET List Knowledge Bases POST Create a Knowledge Base POST Create Presigned URLs for Data Source File Upload GET List Data Sources for a Knowledge Base POST Add Data Source to a Knowledge Base PUT Update Data Source options DELETE Delete a Data Source from a Knowledge Base GET List Indexing Jobs for a Knowledge Base GET Retrieve Information About an Existing Knowledge Base PUT Update a Knowledge Base DELETE Delete a Knowledge Base GET List Available Models GET List Model API Keys POST Create a Model API Key PUT Update API Key for a Model DELETE Delete API Key for a Model PUT Regenerate API Key for a Model POST Get Oauth2 Dropbox Tokens GET Get Oauth2 URL GET List OpenAI API Keys POST Create OpenAI API Key GET Get OpenAI API Key PUT Update OpenAI API Key DELETE Delete OpenAI API Key GET List agents by OpenAI key GET List Datacenter Regions POST Create scheduled indexing for knowledge base GET Get Scheduled Indexing for Knowledge Base DELETE Delete Scheduled Indexing GET List Workspaces POST Create a Workspace GET Retrieve an Existing Workspace PUT Update a Workspace DELETE Delete a Workspace GET List agents by Workspace PUT Move Agents to a Workspace GET List Evaluation Test Cases by Workspace

GET List Agents

/v2/gen-ai/agents
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all agents, send a GET request to /v2/gen-ai/agents.

Query Parameters

only_deployed boolean optional
Example: true

Only list agents that are deployed.

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/agents
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agents array of object optional

Agents

Show child properties
chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

created_at string (date-time) optional
Example: 2021-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: This is a chatbot that can help you with your questions.

Description of agent

if_case string optional
Example: if talking about the weather use this route

Instructions to the agent on how to use the route

instruction string optional
Example: Hello, how can I help you?

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 5

How many results should be considered from an attached knowledge base

max_tokens integer (int64) optional
Example: 100

Specifies the maximum number of tokens the model can process in a single input or output, set as a number between 1 and 512. This determines the length of each response.

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

name string optional
Example: My Agent

Agent name

project_id string optional
Example: 12345678-1234-1234-1234-123456789012

The DigitalOcean project ID associated with the agent

provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: "tor1"

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2021-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345678

Id of user that created the route

route_name string optional
Example: Route Name

Route name

route_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Route uuid

tags array of string optional
Example: ["example string"]

A set of abitrary tags to organize your agent

temperature number (float) optional
Example: 0.5

Controls the model’s creativity, specified as a number between 0 and 1. Lower values produce more predictable and conservative responses, while higher values encourage creativity and variation.

template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 0.9

Defines the cumulative probability threshold for word selection, specified as a number between 0 and 1. Higher values allow for more diverse outputs, while lower values ensure focused and coherent responses.

updated_at string (date-time) optional
Example: 2021-01-01T00:00:00Z

Last modified

url string optional
Example: https://example.com/agent

Access your agent under this url

user_id string (uint64) optional
Example: 12345678

Id of user that created the agent

uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agents": [
    {
      "chatbot_identifiers": [],
      "created_at": "2021-01-01T00:00:00Z",
      "description": "This is a chatbot that can help you with your questions.",
      "if_case": "if talking about the weather use this route",
      "instruction": "Hello, how can I help you?",
      "k": 5,
      "max_tokens": 100,
      "name": "My Agent",
      "project_id": "12345678-1234-1234-1234-123456789012",
      "provide_citations": true,
      "region": "\"tor1\"",
      "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
      "route_created_at": "2021-01-01T00:00:00Z",
      "route_created_by": "12345678",
      "route_name": "Route Name",
      "route_uuid": "\"12345678-1234-1234-1234-123456789012\"",
      "tags": [
        "example string"
      ],
      "temperature": 0.5,
      "top_p": 0.9,
      "updated_at": "2021-01-01T00:00:00Z",
      "url": "https://example.com/agent",
      "user_id": "12345678",
      "uuid": "\"12345678-1234-1234-1234-123456789012\"",
      "version_hash": "example string"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create an Agent

/v2/gen-ai/agents
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create a new agent, send a POST request to /v2/gen-ai/agents. The response body contains a JSON object with the newly created agent object.

Request Body: application/json

anthropic_key_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Optional Anthropic API key ID to use with Anthropic models

description string optional
Example: "My Agent Description"

A text description of the agent, not used in inference

instruction string optional
Example: "You are an agent who thinks deeply about the world"

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

knowledge_base_uuid array of string optional
Example: ["example string"]

Ids of the knowledge base(s) to attach to the agent

model_provider_key_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
model_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Identifier for the foundation model.

name string optional
Example: "My Agent"

Agent name

open_ai_key_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Optional OpenAI API key ID to use with OpenAI models

project_id string optional
Example: "12345678-1234-1234-1234-123456789012"

The id of the DigitalOcean project this agent will belong to

region string optional
Example: "tor1"

The DigitalOcean region to deploy your agent in

tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the workspace

Request: /v2/gen-ai/agents
Content type application/json 
{
  "anthropic_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "description": "\"My Agent Description\"",
  "instruction": "\"You are an agent who thinks deeply about the world\"",
  "knowledge_base_uuid": [
    "example string"
  ],
  "model_provider_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "model_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"My Agent\"",
  "open_ai_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "project_id": "\"12345678-1234-1234-1234-123456789012\"",
  "region": "\"tor1\"",
  "tags": [
    "example string"
  ],
  "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
curl -X POST \
    -H "Content-Type: application/json"  \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    "https://api.digitalocean.com/v2/gen-ai/agents" \
    -d '{
      "name": "api-create",
      "model_uuid": "95ea6652-75ed-11ef-bf8f-4e013e2ddde4",
      "instruction": "be a weather reporter",
      "description": "weather-agent",
      "project_id": "37455431-84bd-4fa2-94cf-e8486f8f8c5e",
      "tags": [
        "tag1"
      ],
      "region": "tor1",
      "knowledge_base_uuid": [
        "9758a232-b351-11ef-bf8f-4e013e2ddde4"
      ]
    }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Agent API Keys

/v2/gen-ai/agents/{agent_uuid}/api_keys
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all agent API keys, send a GET request to /v2/gen-ai/agents/{agent_uuid}/api_keys.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent id

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/agents/{agent_uuid}/api_keys
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/api_keys"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_infos": [
    {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "secret_key": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create an Agent API Key

/v2/gen-ai/agents/{agent_uuid}/api_keys
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create an agent API key, send a POST request to /v2/gen-ai/agents/{agent_uuid}/api_keys.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent id

Request Body: application/json

agent_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Agent id

name string optional
Example: Production Key

A human friendly name to identify the key

Request: /v2/gen-ai/agents/{agent_uuid}/api_keys
Content type application/json 
{
  "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "Production Key"
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys" \
  -d '{
    "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "name": "test-key"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Agent API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "secret_key": "example string",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update API Key for an Agent

/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update an agent API key, send a PUT request to /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent id

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key ID

Request Body: application/json

agent_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Agent id

api_key_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

API key ID

name string optional
Example: "Production Key"

Name

Request: /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}
Content type application/json 
{
  "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"Production Key\""
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \
  -d '{
    "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4",
    "name": "test-key2"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Agent API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "secret_key": "example string",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete API Key for an Agent

/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete an API key for an agent, send a DELETE request to /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

A unique identifier for your agent.

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key for an agent.

Request: /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Agent API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "secret_key": "example string",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Regenerate API Key for an Agent

/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To regenerate an agent API key, send a PUT request to /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent id

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key ID

Request: /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys/11efcf7e-824d-2808-bf8f-4e013e2ddde4/regenerate"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Agent API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "secret_key": "example string",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Add Function Route to an Agent

/v2/gen-ai/agents/{agent_uuid}/functions
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create a function route for an agent, send a POST request to /v2/gen-ai/agents/{agent_uuid}/functions.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent id

Request Body: application/json

agent_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Agent id

description string optional
Example: "My Function Description"

Function description

faas_name string optional
Example: "my-function"

The name of the function in the DigitalOcean functions platform

faas_namespace string optional
Example: "default"

The namespace of the function in the DigitalOcean functions platform

function_name string optional
Example: "My Function"

Function name

input_schema object optional

Describe the input schema for the function so the agent may call it

output_schema object optional

Describe the output schema for the function so the agent handle its response

Request: /v2/gen-ai/agents/{agent_uuid}/functions
Content type application/json 
{
  "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "description": "\"My Function Description\"",
  "faas_name": "\"my-function\"",
  "faas_namespace": "\"default\"",
  "function_name": "\"My Function\""
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/functions" \
  -d '{
    "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "function_name": "funzip",
    "description": "Use when you need the zipcode for a city",
    "input_schema": {
      "city": {
        "description": "the city you want a zipcode for",
        "required": true,
        "type": "string"
      }
    },
    "output_schema": {
      "zip_code": {
        "description": "The zipcode of the desired city",
        "type": "number"
      }
    },
    "faas_namespace": "fn-2014dc98-faa1-45f4-ba1f-59910cb3d399",
    "faas_name": "default/get-zipcode"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update Function Route for an Agent

/v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update the function route, send a PUT request to /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent id

function_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Function id

Request Body: application/json

agent_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Agent id

description string optional
Example: "My Function Description"

Funciton description

faas_name string optional
Example: "my-function"

The name of the function in the DigitalOcean functions platform

faas_namespace string optional
Example: "default"

The namespace of the function in the DigitalOcean functions platform

function_name string optional
Example: "My Function"

Function name

function_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Function id

input_schema object optional

Describe the input schema for the function so the agent may call it

output_schema object optional

Describe the output schema for the function so the agent handle its response

Request: /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}
Content type application/json 
{
  "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "description": "\"My Function Description\"",
  "faas_name": "\"my-function\"",
  "faas_namespace": "\"default\"",
  "function_name": "\"My Function\"",
  "function_uuid": "\"12345678-1234-1234-1234-123456789012\""
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/functions/b00e74f6-985c-11ef-bf8f-4e013e2ddde4" \
  -d '{
    "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "function_uuid": "6cc5cda5-9ac3-11ef-bf8f-4e013e2ddde4",
    "function_name": "func-rename"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete Function Route for an Agent

/v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete a function route from an agent, send a DELETE request to /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

The id of the agent the function route belongs to.

function_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

The function route to be destroyed. This does not destroy the function itself.

Request: /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/ff47f5b7-96e5-11ef-bf8f-4e013e2ddde4/functions/6cc5cda5-9ac3-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Attach Guardrails to an Agent

/v2/gen-ai/agents/{agent_uuid}/guardrails
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To attach guardrails to an agent, send a POST request to /v2/gen-ai/agents/{agent_uuid}/guardrails.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

The UUID of the agent.

Request Body: application/json

agent_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

The UUID of the agent.

guardrails array of object optional

The list of guardrails to attach.

Show child properties
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Guardrail uuid

priority integer (int64) optional
Example: 123

Priority of the guardrail

Request: /v2/gen-ai/agents/{agent_uuid}/guardrails
Content type application/json 
{
  "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "guardrails": [
    {
      "guardrail_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "priority": 123
    }
  ]
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1c8be326-00fe-11f1-b542-ca68c578b05c/guardrails" \
  -d '{
    "guardrails": [
      {
        "guardrail_uuid": "69bcc61c-2bb2-49fd-b6ed-7c1bd73d6442",
        "priority": 1
      },
      {
        "guardrail_uuid": "dc72b12b-bd45-46c9-bca1-00a6624aac3a",
        "priority": 2
      }
    ]
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Detach a Guardrail from an Agent

/v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To detach a guardrail from an agent, send a DELETE request to /v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

The UUID of the agent.

guardrail_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

The UUID of the guardrail to detach.

Request: /v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}
curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1c8be326-00fe-11f1-b542-ca68c578b04c/guardrails/69bcc61c-2bb2-49fd-b6ed-7c1bd73d6572"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Attach Knowledge Bases to an Agent

/v2/gen-ai/agents/{agent_uuid}/knowledge_bases
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To attach knowledge bases to an agent, send a POST request to /v2/gen-ai/agents/{agent_uuid}/knowledge_bases

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

A unique identifier for an agent.

Request: /v2/gen-ai/agents/{agent_uuid}/knowledge_bases
curl -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
 "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/knowledge_bases" \
 -d '{
   "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
   "knowledge_base_uuids": [
     "9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4",
     "683c3100-7c18-4c94-aea4-5ac5875cc87c",
     "4887a78b-74af-46b3-98f4-451a48f9cc5e"
   ]
 }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Attach Knowledge Base to an Agent

/v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To attach a knowledge base to an agent, send a POST request to /v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

A unique identifier for an agent.

knowledge_base_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

A unique identifier for a knowledge base.

Request: /v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/knowledge_bases/9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4" \
  -d '{
    "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "agent_uuid": "9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Detach Knowledge Base from an Agent

/v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To detach a knowledge base from an agent, send a DELETE request to /v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}.

Path Parameters

agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent id

knowledge_base_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Knowledge base id

Request: /v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4/data_sources/bd2a2db5-b8b0-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Add Agent Route to an Agent

/v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To add an agent route to an agent, send a POST request to /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}.

Path Parameters

parent_agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

A unique identifier for the parent agent.

child_agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Routed agent id

Request Body: application/json

child_agent_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Routed agent id

if_case string optional
Example: "use this to get weather information"
parent_agent_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

A unique identifier for the parent agent.

route_name string optional
Example: "weather_route"

Name of route

Request: /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}
Content type application/json 
{
  "child_agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "if_case": "\"use this to get weather information\"",
  "parent_agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "route_name": "\"weather_route\""
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/child_agents/6a09d603-b68d-11ef-bf8f-4e013e2ddde4" \
  -d '{
    "parent_agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "child_agent_uuid": "6a09d603-b68d-11ef-bf8f-4e013e2ddde4",
    "route_name": "route-token-stat",
    "if_case": "for any token related statistics, use this route"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
child_agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Routed agent id

parent_agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

A unique identifier for the parent agent.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "child_agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "parent_agent_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update Agent Route for an Agent

/v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update an agent route for an agent, send a PUT request to /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}.

Path Parameters

parent_agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

A unique identifier for the parent agent.

child_agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Routed agent id

Request Body: application/json

child_agent_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Routed agent id

if_case string optional
Example: "use this to get weather information"

Describes the case in which the child agent should be used

parent_agent_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

A unique identifier for the parent agent.

route_name string optional
Example: "weather_route"

Route name

uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Unique id of linkage

Request: /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}
Content type application/json 
{
  "child_agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "if_case": "\"use this to get weather information\"",
  "parent_agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "route_name": "\"weather_route\"",
  "uuid": "\"12345678-1234-1234-1234-123456789012\""
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/child_agents/18c4c90c-cc40-11ef-bf8f-4e013e2ddde4" \
  -d '{
    "parent_agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "child_agent_uuid": "18c4c90c-cc40-11ef-bf8f-4e013e2ddde4",
    "route_name": "route-rename-api",
    "if_case": "if any token related statistics, use this route only",
    "uuid":"a22d2004-bbaa-11ef-bf8f-4e013e2ddde4"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
child_agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Routed agent id

parent_agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

A unique identifier for the parent agent.

rollback boolean optional
Example: true
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of linkage

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "child_agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "parent_agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "rollback": true,
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete Agent Route for an Agent

/v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete an agent route from a parent agent, send a DELETE request to /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}.

Path Parameters

parent_agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Pagent agent id

child_agent_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Routed agent id

Request: /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/ff47f5b7-96e5-11ef-bf8f-4e013e2ddde4/child_agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
child_agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Routed agent id

parent_agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Pagent agent id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "child_agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "parent_agent_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an Existing Agent

/v2/gen-ai/agents/{uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To retrieve details of an agent, GET request to /v2/gen-ai/agents/{uuid}. The response body is a JSON object containing the agent.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Unique agent id

Request: /v2/gen-ai/agents/{uuid}
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update an Agent

/v2/gen-ai/agents/{uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update an agent, send a PUT request to /v2/gen-ai/agents/{uuid}. The response body is a JSON object containing the agent.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Unique agent id

Request Body: application/json

agent_log_insights_enabled boolean optional
Example: true
allowed_domains array of string optional
Example: ["example string"]

Optional list of allowed domains for the chatbot - Must use fully qualified domain name (FQDN) such as https://example.com

anthropic_key_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Optional anthropic key uuid for use with anthropic models

conversation_logs_enabled boolean optional
Example: true

Optional update of conversation logs enabled

description string optional
Example: "My Agent Description"

Agent description

instruction string optional
Example: "You are an agent who thinks deeply about the world"

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 5

How many results should be considered from an attached knowledge base

max_tokens integer (int64) optional
Example: 100

Specifies the maximum number of tokens the model can process in a single input or output, set as a number between 1 and 512. This determines the length of each response.

model_provider_key_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Optional Model Provider uuid for use with provider models

model_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Identifier for the foundation model.

name string optional
Example: "My New Agent Name"

Agent name

open_ai_key_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Optional OpenAI key uuid for use with OpenAI models

project_id string optional
Example: "12345678-1234-1234-1234-123456789012"

The id of the DigitalOcean project this agent will belong to

provide_citations boolean optional
Example: true
retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
tags array of string optional
Example: ["example string"]

A set of abitrary tags to organize your agent

temperature number (float) optional
Example: 0.7

Controls the model’s creativity, specified as a number between 0 and 1. Lower values produce more predictable and conservative responses, while higher values encourage creativity and variation.

top_p number (float) optional
Example: 0.9

Defines the cumulative probability threshold for word selection, specified as a number between 0 and 1. Higher values allow for more diverse outputs, while lower values ensure focused and coherent responses.

uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Unique agent id

Request: /v2/gen-ai/agents/{uuid}
Content type application/json 
{
  "agent_log_insights_enabled": true,
  "allowed_domains": [
    "example string"
  ],
  "anthropic_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "conversation_logs_enabled": true,
  "description": "\"My Agent Description\"",
  "instruction": "\"You are an agent who thinks deeply about the world\"",
  "k": 5,
  "max_tokens": 100,
  "model_provider_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "model_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"My New Agent Name\"",
  "open_ai_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "project_id": "\"12345678-1234-1234-1234-123456789012\"",
  "provide_citations": true,
  "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
  "tags": [
    "example string"
  ],
  "temperature": 0.7,
  "top_p": 0.9,
  "uuid": "\"12345678-1234-1234-1234-123456789012\""
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4" \
  -d '{
    "uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "name": "rename-agent-api",
    "instruction": "be a weather reporter and act like you are a pro",
    "description": "weather-agent2",
    "model_uuid": "95ea6652-75ed-11ef-bf8f-4e013e2ddde4",
    "project_id": "37455431-84bd-4fa2-94cf-e8486f8f8c5e",
    "tags": [
      "tag2"
    ],
    "k": 5,
    "temperature": 1,
    "top_p": 1,
    "max_tokens": 250
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete an Agent

/v2/gen-ai/agents/{uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete an agent, send a DELETE request to /v2/gen-ai/agents/{uuid}.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Unique agent id

Request: /v2/gen-ai/agents/{uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agent/5581a586-a745-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET View Agent Routes

/v2/gen-ai/agents/{uuid}/child_agents
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To view agent routes for an agent, send a GET requtest to /v2/gen-ai/agents/{uuid}/child_agents.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent id

Request: /v2/gen-ai/agents/{uuid}/child_agents
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/child_agents"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
children array of object optional

Child agents

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "children": [
    {
      "api_key_infos": [],
      "api_keys": [],
      "chatbot_identifiers": [],
      "child_agents": [],
      "conversation_logs_enabled": true,
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "functions": [],
      "guardrails": [],
      "if_case": "example string",
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "max_tokens": 123,
      "name": "example name",
      "parent_agents": [],
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "provide_citations": true,
      "region": "example string",
      "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
      "route_created_at": "2023-01-01T00:00:00Z",
      "route_created_by": "12345",
      "route_name": "example name",
      "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "user_id": "12345",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "version_hash": "example string",
      "vpc_egress_ips": [
        "example string"
      ],
      "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\""
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update Agent Status

/v2/gen-ai/agents/{uuid}/deployment_visibility
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Check whether an agent is public or private. To update the agent status, send a PUT request to /v2/gen-ai/agents/{uuid}/deployment_visibility.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Unique id

Request Body: application/json

uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
Request: /v2/gen-ai/agents/{uuid}/deployment_visibility
Content type application/json 
{
  "uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "visibility": "VISIBILITY_UNKNOWN"
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/deployment_visibility" \
  -d '{
    "uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "visibility": "VISIBILITY_PUBLIC"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent object optional

An Agent

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Get Agent Usage

/v2/gen-ai/agents/{uuid}/usage
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To get agent usage, send a GET request to /v2/gen-ai/agents/{uuid}/usage. Returns usage metrics for the specified agent within the provided time range.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent id

Query Parameters

start string optional
Example: "example string"

Return all usage data from this date.

stop string optional
Example: "example string"

Return all usage data up to this date, if omitted, will return up to the current date.

Request: /v2/gen-ai/agents/{uuid}/usage
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/genai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/usage?start=2024-01-01T00:00:00Z&stop=2024-01-31T23:59:59Z"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
log_insights_usage object optional

Resource Usage Description

Show child properties
measurements array of object optional
Show child properties
tokens integer (int64) optional
Example: 123
usage_type string optional
Example: example string
resource_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
start string (date-time) optional
Example: 2023-01-01T00:00:00Z
stop string (date-time) optional
Example: 2023-01-01T00:00:00Z
usage object optional

Resource Usage Description

Show child properties
measurements array of object optional
Show child properties
tokens integer (int64) optional
Example: 123
usage_type string optional
Example: example string
resource_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
start string (date-time) optional
Example: 2023-01-01T00:00:00Z
stop string (date-time) optional
Example: 2023-01-01T00:00:00Z
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "log_insights_usage": {
    "measurements": [],
    "resource_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "start": "2023-01-01T00:00:00Z",
    "stop": "2023-01-01T00:00:00Z"
  },
  "usage": {
    "measurements": [],
    "resource_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "start": "2023-01-01T00:00:00Z",
    "stop": "2023-01-01T00:00:00Z"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Agent Versions

/v2/gen-ai/agents/{uuid}/versions
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all agent versions, send a GET request to /v2/gen-ai/agents/{uuid}/versions.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent uuid

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/agents/{uuid}/versions
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/versions"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agent_versions array of object optional

Agents

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the agent this version belongs to

attached_child_agents array of object optional

List of child agent relationships

Show child properties
agent_name string optional
Example: example name

Name of the child agent

child_agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Child agent unique identifier

if_case string optional
Example: example string

If case

is_deleted boolean optional
Example: true

Child agent is deleted

route_name string optional
Example: example name

Route name

attached_functions array of object optional

List of function versions

Show child properties
description string optional
Example: example string

Description of the function

faas_name string optional
Example: example name

FaaS name of the function

faas_namespace string optional
Example: example name

FaaS namespace of the function

is_deleted boolean optional
Example: true

Whether the function is deleted

name string optional
Example: example name

Name of the function

attached_guardrails array of object optional

List of guardrail version

Show child properties
is_deleted boolean optional
Example: true

Whether the guardrail is deleted

name string optional
Example: example name

Guardrail Name

priority integer (int64) optional
Example: 123

Guardrail Priority

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Guardrail UUID

attached_knowledgebases array of object optional

List of knowledge base agent versions

Show child properties
is_deleted boolean optional
Example: true

Deletet at date / time

name string optional
Example: example name

Name of the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the knowledge base

can_rollback boolean optional
Example: true

Whether the version is able to be rolled back to

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by_email string optional
Example: [email protected]

User who created this version

currently_applied boolean optional
Example: true

Whether this is the currently applied configuration

description string optional
Example: example string

Description of the agent

id string (uint64) optional
Example: 12345

Unique identifier

instruction string optional
Example: example string

Instruction for the agent

k integer (int64) optional
Example: 123

K value for the agent's configuration

max_tokens integer (int64) optional
Example: 123

Max tokens setting for the agent

model_name string optional
Example: example name

Name of model associated to the agent version

name string optional
Example: example name

Name of the agent

provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
tags array of string optional
Example: ["example string"]

Tags associated with the agent

temperature number (float) optional
Example: 123

Temperature setting for the agent

top_p number (float) optional
Example: 123

Top_p setting for the agent

trigger_action string optional
Example: example string

Action triggering the configuration update

version_hash string optional
Example: example string

Version hash

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agent_versions": [
    {
      "agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "attached_child_agents": [],
      "attached_functions": [],
      "attached_guardrails": [],
      "attached_knowledgebases": [],
      "can_rollback": true,
      "created_at": "2023-01-01T00:00:00Z",
      "created_by_email": "[email protected]",
      "currently_applied": true,
      "description": "example string",
      "id": "12345",
      "instruction": "example string",
      "k": 123,
      "max_tokens": 123,
      "model_name": "example name",
      "name": "example name",
      "provide_citations": true,
      "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "top_p": 123,
      "trigger_action": "example string",
      "version_hash": "example string"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Rollback to Agent Version

/v2/gen-ai/agents/{uuid}/versions
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update to a specific agent version, send a PUT request to /v2/gen-ai/agents/{uuid}/versions.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Agent unique identifier

Request Body: application/json

uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Agent unique identifier

version_hash string optional
Example: c3658d8b5c05494cd03ce042926ef08157889ed54b1b74b5ee0b3d66dcee4b73

Unique identifier

Request: /v2/gen-ai/agents/{uuid}/versions
Content type application/json 
{
  "uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "version_hash": "c3658d8b5c05494cd03ce042926ef08157889ed54b1b74b5ee0b3d66dcee4b73"
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/versions" \
  -d '{
    "uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "version_hash": "c3658d8b5c05494cd03ce042926ef08157889ed54b1b74b5ee0b3d66dcee4b73"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
audit_header object optional

An alternative way to provide auth information. for internal use only.

Show child properties
actor_id string (uint64) optional
Example: 12345
actor_ip string optional
Example: example string
actor_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
context_urn string optional
Example: example string
origin_application string optional
Example: example string
user_id string (uint64) optional
Example: 12345
user_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
version_hash string optional
Example: example string

Unique identifier

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "audit_header": {
    "actor_id": "12345",
    "actor_ip": "example string",
    "actor_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "context_urn": "example string",
    "origin_application": "example string",
    "user_id": "12345",
    "user_uuid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "version_hash": "example string"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Anthropic API Keys

/v2/gen-ai/anthropic/keys
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all Anthropic API keys, send a GET request to /v2/gen-ai/anthropic/keys.

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/anthropic/keys
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/anthropic/keys"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_infos": [
    {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create Anthropic API Key

/v2/gen-ai/anthropic/keys
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create an Anthropic API key, send a POST request to /v2/gen-ai/anthropic/keys.

Request Body: application/json

api_key string optional
Example: "sk-ant-12345678901234567890123456789012"

Anthropic API key

name string optional
Example: "Production Key"

Name of the key

Request: /v2/gen-ai/anthropic/keys
Content type application/json 
{
  "api_key": "\"sk-ant-12345678901234567890123456789012\"",
  "name": "\"Production Key\""
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/anthropic/keys" \
  -d '{
    "api_key": "sk-ant-12345678901234567890123456789012",
    "name": "test-key"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Get Anthropic API Key

/v2/gen-ai/anthropic/keys/{api_key_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To retrieve details of an Anthropic API key, send a GET request to /v2/gen-ai/anthropic/keys/{api_key_uuid}.

Path Parameters

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key ID

Request: /v2/gen-ai/anthropic/keys/{api_key_uuid}
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update Anthropic API Key

/v2/gen-ai/anthropic/keys/{api_key_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update an Anthropic API key, send a PUT request to /v2/gen-ai/anthropic/keys/{api_key_uuid}.

Path Parameters

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key ID

Request Body: application/json

api_key string optional
Example: "sk-ant-12345678901234567890123456789012"

Anthropic API key

api_key_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

API key ID

name string optional
Example: "Production Key"

Name of the key

Request: /v2/gen-ai/anthropic/keys/{api_key_uuid}
Content type application/json 
{
  "api_key": "\"sk-ant-12345678901234567890123456789012\"",
  "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"Production Key\""
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \
  -d '{
    "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4",
    "name": "test-key2"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete Anthropic API Key

/v2/gen-ai/anthropic/keys/{api_key_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete an Anthropic API key, send a DELETE request to /v2/gen-ai/anthropic/keys/{api_key_uuid}.

Path Parameters

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key ID

Request: /v2/gen-ai/anthropic/keys/{api_key_uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List agents by Anthropic key

/v2/gen-ai/anthropic/keys/{uuid}/agents
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

List Agents by Anthropic Key.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Unique ID of Anthropic key

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/anthropic/keys/{uuid}/agents
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/agents"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agents array of object optional
Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agents": [
    {
      "api_key_infos": [],
      "api_keys": [],
      "chatbot_identifiers": [],
      "child_agents": [],
      "conversation_logs_enabled": true,
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "functions": [],
      "guardrails": [],
      "if_case": "example string",
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "max_tokens": 123,
      "name": "example name",
      "parent_agents": [],
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "provide_citations": true,
      "region": "example string",
      "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
      "route_created_at": "2023-01-01T00:00:00Z",
      "route_created_by": "12345",
      "route_name": "example name",
      "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "user_id": "12345",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "version_hash": "example string",
      "vpc_egress_ips": [
        "example string"
      ],
      "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\""
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create Evaluation Dataset

/v2/gen-ai/evaluation_datasets
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create an evaluation dataset, send a POST request to /v2/gen-ai/evaluation_datasets.

Request Body: application/json

dataset_type string, one of: EVALUATION_DATASET_TYPE_UNKNOWN, EVALUATION_DATASET_TYPE_ADK, EVALUATION_DATASET_TYPE_NON_ADK optional
Example: EVALUATION_DATASET_TYPE_UNKNOWN
file_upload_dataset object optional

File to upload as data source for knowledge base.

Show child properties
original_file_name string optional
Example: example name

The original file name

size_in_bytes string (uint64) optional
Example: 12345

The size of the file in bytes

stored_object_key string optional
Example: example string

The object key the file was stored as

name string optional
Example: example name

The name of the agent evaluation dataset.

Request: /v2/gen-ai/evaluation_datasets
Content type application/json 
{
  "dataset_type": "EVALUATION_DATASET_TYPE_UNKNOWN",
  "file_upload_dataset": {
    "original_file_name": "example name",
    "size_in_bytes": "12345",
    "stored_object_key": "example string"
  },
  "name": "example name"
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_datasets" \
  -d '{
    "name": "dataset.csv",
    "file_upload_dataset": {
      "original_file_name": "dataset.csv",
      "stored_object_key": "123abc",
      "size_in_bytes": 255
    }
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
evaluation_dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Evaluation dataset uuid.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "evaluation_dataset_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create Presigned URLs for Evaluation Dataset File Upload

/v2/gen-ai/evaluation_datasets/file_upload_presigned_urls
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create presigned URLs for evaluation dataset file upload, send a POST request to /v2/gen-ai/evaluation_datasets/file_upload_presigned_urls.

Request Body: application/json

files array of object optional

A list of files to generate presigned URLs for.

Show child properties
file_name string optional
Example: example name

Local filename

file_size string (int64) optional
Example: 12345

The size of the file in bytes.

Request: /v2/gen-ai/evaluation_datasets/file_upload_presigned_urls
Content type application/json 
{
  "files": [
    {
      "file_name": "example name",
      "file_size": "12345"
    }
  ]
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_datasets/file_upload_presigned_urls" \
  -d '{
    "files": [{
      "file_name": "dataset.csv",
      "file_size": 2048
    }]
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
request_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The ID generated for the request for Presigned URLs.

uploads array of object optional

A list of generated presigned URLs and object keys, one per file.

Show child properties
expires_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The time the url expires at.

object_key string optional
Example: example string

The unique object key to store the file as.

original_file_name string optional
Example: example name

The original file name.

presigned_url string optional
Example: example string

The actual presigned URL the client can use to upload the file directly.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "uploads": [
    {
      "expires_at": "2023-01-01T00:00:00Z",
      "object_key": "example string",
      "original_file_name": "example name",
      "presigned_url": "example string"
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Evaluation Metrics

/v2/gen-ai/evaluation_metrics
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all evaluation metrics, send a GET request to /v2/gen-ai/evaluation_metrics.

Request: /v2/gen-ai/evaluation_metrics
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_metrics"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
metrics array of object optional
Show child properties
category string (enum) optional
Example: METRIC_CATEGORY_UNSPECIFIED
description string optional
Example: example string
inverted boolean optional
Example: true

If true, the metric is inverted, meaning that a lower value is better.

is_metric_goal boolean optional
Example: true
metric_name string optional
Example: example name
metric_rank integer (int64) optional
Example: 123
metric_type string, one of: METRIC_TYPE_UNSPECIFIED, METRIC_TYPE_GENERAL_QUALITY, METRIC_TYPE_RAG_AND_TOOL optional
Example: METRIC_TYPE_UNSPECIFIED
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
range_max number (float) optional
Example: 123

The maximum value for the metric.

range_min number (float) optional
Example: 123

The minimum value for the metric.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "metrics": [
    {
      "category": "METRIC_CATEGORY_UNSPECIFIED",
      "description": "example string",
      "inverted": true,
      "is_metric_goal": true,
      "metric_name": "example name",
      "metric_rank": 123,
      "metric_type": "METRIC_TYPE_UNSPECIFIED",
      "metric_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "metric_value_type": "METRIC_VALUE_TYPE_UNSPECIFIED",
      "range_max": 123,
      "range_min": 123
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Run an Evaluation Test Case

/v2/gen-ai/evaluation_runs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To run an evaluation test case, send a POST request to /v2/gen-ai/evaluation_runs.

Request Body: application/json

agent_deployment_names array of string optional
Example: ["example string"]

Agent deployment names to run the test case against (ADK agent workspaces).

agent_uuids array of string optional
Example: ["example string"]

Agent UUIDs to run the test case against (legacy agents).

run_name string optional
Example: Evaluation Run Name

The name of the run.

test_case_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Test-case UUID to run

Request: /v2/gen-ai/evaluation_runs
Content type application/json 
{
  "agent_deployment_names": [
    "example string"
  ],
  "agent_uuids": [
    "example string"
  ],
  "run_name": "Evaluation Run Name",
  "test_case_uuid": "\"12345678-1234-1234-1234-123456789012\""
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_runs" \
  -d '{
    "test_case_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "agent_uuids": ["1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "2b418231-b7d6-11ef-bf8f-4e013e2ddde4"],
    "run_name": "My Evaluation Run",
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
evaluation_run_uuids array of string optional
Example: ["example string"]
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "evaluation_run_uuids": [
    "example string"
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Information About an Existing Evaluation Run

/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To retrive information about an existing evaluation run, send a GET request to /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}.

Path Parameters

evaluation_run_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Evaluation run UUID.

Request: /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_runs/9758a232-b351-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
evaluation_run object optional
Show child properties
agent_deleted boolean optional
Example: true

Whether agent is deleted

agent_deployment_name string optional
Example: example name

The agent deployment name

agent_name string optional
Example: example name

Agent name

agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent UUID.

agent_version_hash string optional
Example: example string

Version hash

agent_workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent workspace uuid

created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
error_description string optional
Example: example string

The error description

evaluation_run_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Evaluation run UUID.

evaluation_test_case_workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Evaluation test case workspace uuid

finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Run end time.

pass_status boolean optional
Example: true

The pass status of the evaluation run based on the star metric.

queued_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Run queued time.

run_level_metric_results array of object optional
Show child properties
error_description string optional
Example: example string

Error description if the metric could not be calculated.

metric_name string optional
Example: example name

Metric name

metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
number_value number (double) optional
Example: 123

The value of the metric as a number.

reasoning string optional
Example: example string

Reasoning of the metric result.

string_value string optional
Example: example string

The value of the metric as a string.

run_name string optional
Example: example name

Run name.

star_metric_result object optional
Show child properties
error_description string optional
Example: example string

Error description if the metric could not be calculated.

metric_name string optional
Example: example name

Metric name

metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
number_value number (double) optional
Example: 123

The value of the metric as a number.

reasoning string optional
Example: example string

Reasoning of the metric result.

string_value string optional
Example: example string

The value of the metric as a string.

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Run start time.

status string (enum) optional
Example: EVALUATION_RUN_STATUS_UNSPECIFIED

Evaluation Run Statuses

test_case_description string optional
Example: example string

Test case description.

test_case_name string optional
Example: example name

Test case name.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Test-case UUID.

test_case_version integer (int64) optional
Example: 123

Test-case-version.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "evaluation_run": {
    "agent_deleted": true,
    "agent_deployment_name": "example name",
    "agent_name": "example name",
    "agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "agent_version_hash": "example string",
    "agent_workspace_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "created_by_user_email": "[email protected]",
    "created_by_user_id": "12345",
    "error_description": "example string",
    "evaluation_run_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "evaluation_test_case_workspace_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "finished_at": "2023-01-01T00:00:00Z",
    "pass_status": true,
    "queued_at": "2023-01-01T00:00:00Z",
    "run_level_metric_results": [],
    "run_name": "example name",
    "star_metric_result": {
      "error_description": "example string",
      "metric_name": "example name",
      "metric_value_type": "METRIC_VALUE_TYPE_UNSPECIFIED",
      "number_value": 123,
      "reasoning": "example string",
      "string_value": "example string"
    },
    "started_at": "2023-01-01T00:00:00Z",
    "status": "EVALUATION_RUN_STATUS_UNSPECIFIED",
    "test_case_description": "example string",
    "test_case_name": "example name",
    "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "test_case_version": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Results of an Evaluation Run

/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To retrieve results of an evaluation run, send a GET request to /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results.

Path Parameters

evaluation_run_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Evaluation run UUID.

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_runs/9758a232-b351-11ef-bf8f-4e013e2ddde4/results"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
evaluation_run object optional
Show child properties
agent_deleted boolean optional
Example: true

Whether agent is deleted

agent_deployment_name string optional
Example: example name

The agent deployment name

agent_name string optional
Example: example name

Agent name

agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent UUID.

agent_version_hash string optional
Example: example string

Version hash

agent_workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent workspace uuid

created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
error_description string optional
Example: example string

The error description

evaluation_run_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Evaluation run UUID.

evaluation_test_case_workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Evaluation test case workspace uuid

finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Run end time.

pass_status boolean optional
Example: true

The pass status of the evaluation run based on the star metric.

queued_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Run queued time.

run_level_metric_results array of object optional
Show child properties
error_description string optional
Example: example string

Error description if the metric could not be calculated.

metric_name string optional
Example: example name

Metric name

metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
number_value number (double) optional
Example: 123

The value of the metric as a number.

reasoning string optional
Example: example string

Reasoning of the metric result.

string_value string optional
Example: example string

The value of the metric as a string.

run_name string optional
Example: example name

Run name.

star_metric_result object optional
Show child properties
error_description string optional
Example: example string

Error description if the metric could not be calculated.

metric_name string optional
Example: example name

Metric name

metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
number_value number (double) optional
Example: 123

The value of the metric as a number.

reasoning string optional
Example: example string

Reasoning of the metric result.

string_value string optional
Example: example string

The value of the metric as a string.

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Run start time.

status string (enum) optional
Example: EVALUATION_RUN_STATUS_UNSPECIFIED

Evaluation Run Statuses

test_case_description string optional
Example: example string

Test case description.

test_case_name string optional
Example: example name

Test case name.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Test-case UUID.

test_case_version integer (int64) optional
Example: 123

Test-case-version.

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

prompts array of object optional

The prompt level results.

Show child properties
evaluation_trace_spans array of object optional

The evaluated trace spans.

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

When the span was created

input object optional

Input data for the span (flexible structure - can be messages array, string, etc.)

name string optional
Example: example name

Name/identifier for the span

output object optional

Output data from the span (flexible structure - can be message, string, etc.)

retriever_chunks array of object optional

Any retriever span chunks that were included as part of the span.

Show child properties
chunk_usage_pct number (double) optional
Example: 123

The usage percentage of the chunk.

chunk_used boolean optional
Example: true

Indicates if the chunk was used in the prompt.

index_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The index uuid (Knowledge Base) of the chunk.

source_name string optional
Example: example name

The source name for the chunk, e.g., the file name or document title.

text string optional
Example: example string

Text content of the chunk.

span_level_metric_results array of object optional

The span-level metric results.

Show child properties
error_description string optional
Example: example string

Error description if the metric could not be calculated.

metric_name string optional
Example: example name

Metric name

metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
number_value number (double) optional
Example: 123

The value of the metric as a number.

reasoning string optional
Example: example string

Reasoning of the metric result.

string_value string optional
Example: example string

The value of the metric as a string.

type string, one of: TRACE_SPAN_TYPE_UNKNOWN, TRACE_SPAN_TYPE_LLM, TRACE_SPAN_TYPE_RETRIEVER, TRACE_SPAN_TYPE_TOOL optional
Example: TRACE_SPAN_TYPE_UNKNOWN

Types of spans in a trace

ground_truth string optional
Example: example string

The ground truth for the prompt.

input string optional
Example: example string
input_tokens string (uint64) optional
Example: 12345

The number of input tokens used in the prompt.

output string optional
Example: example string
output_tokens string (uint64) optional
Example: 12345

The number of output tokens used in the prompt.

prompt_chunks array of object optional

The list of prompt chunks.

Show child properties
chunk_usage_pct number (double) optional
Example: 123

The usage percentage of the chunk.

chunk_used boolean optional
Example: true

Indicates if the chunk was used in the prompt.

index_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The index uuid (Knowledge Base) of the chunk.

source_name string optional
Example: example name

The source name for the chunk, e.g., the file name or document title.

text string optional
Example: example string

Text content of the chunk.

prompt_id integer (int64) optional
Example: 123

Prompt ID

prompt_level_metric_results array of object optional

The metric results for the prompt.

Show child properties
error_description string optional
Example: example string

Error description if the metric could not be calculated.

metric_name string optional
Example: example name

Metric name

metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
number_value number (double) optional
Example: 123

The value of the metric as a number.

reasoning string optional
Example: example string

Reasoning of the metric result.

string_value string optional
Example: example string

The value of the metric as a string.

trace_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The trace id for the prompt.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "evaluation_run": {
    "agent_deleted": true,
    "agent_deployment_name": "example name",
    "agent_name": "example name",
    "agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "agent_version_hash": "example string",
    "agent_workspace_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "created_by_user_email": "[email protected]",
    "created_by_user_id": "12345",
    "error_description": "example string",
    "evaluation_run_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "evaluation_test_case_workspace_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "finished_at": "2023-01-01T00:00:00Z",
    "pass_status": true,
    "queued_at": "2023-01-01T00:00:00Z",
    "run_level_metric_results": [],
    "run_name": "example name",
    "star_metric_result": {
      "error_description": "example string",
      "metric_name": "example name",
      "metric_value_type": "METRIC_VALUE_TYPE_UNSPECIFIED",
      "number_value": 123,
      "reasoning": "example string",
      "string_value": "example string"
    },
    "started_at": "2023-01-01T00:00:00Z",
    "status": "EVALUATION_RUN_STATUS_UNSPECIFIED",
    "test_case_description": "example string",
    "test_case_name": "example name",
    "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "test_case_version": 123
  },
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  },
  "prompts": [
    {
      "evaluation_trace_spans": [],
      "ground_truth": "example string",
      "input": "example string",
      "input_tokens": "12345",
      "output": "example string",
      "output_tokens": "12345",
      "prompt_chunks": [],
      "prompt_id": 123,
      "prompt_level_metric_results": [],
      "trace_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Results of an Evaluation Run Prompt

/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results/{prompt_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To retrieve results of an evaluation run, send a GET request to /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results/{prompt_id}.

Path Parameters

evaluation_run_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Evaluation run UUID.

prompt_id integer required
Example: 1

Prompt ID to get results for.

Request: /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results/{prompt_id}
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_runs/9758a232-b351-11ef-bf8f-4e013e2ddde4/results/c441bf77-81d6-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
prompt object optional
Show child properties
evaluation_trace_spans array of object optional

The evaluated trace spans.

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

When the span was created

input object optional

Input data for the span (flexible structure - can be messages array, string, etc.)

name string optional
Example: example name

Name/identifier for the span

output object optional

Output data from the span (flexible structure - can be message, string, etc.)

retriever_chunks array of object optional

Any retriever span chunks that were included as part of the span.

Show child properties
chunk_usage_pct number (double) optional
Example: 123

The usage percentage of the chunk.

chunk_used boolean optional
Example: true

Indicates if the chunk was used in the prompt.

index_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The index uuid (Knowledge Base) of the chunk.

source_name string optional
Example: example name

The source name for the chunk, e.g., the file name or document title.

text string optional
Example: example string

Text content of the chunk.

span_level_metric_results array of object optional

The span-level metric results.

Show child properties
error_description string optional
Example: example string

Error description if the metric could not be calculated.

metric_name string optional
Example: example name

Metric name

metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
number_value number (double) optional
Example: 123

The value of the metric as a number.

reasoning string optional
Example: example string

Reasoning of the metric result.

string_value string optional
Example: example string

The value of the metric as a string.

type string, one of: TRACE_SPAN_TYPE_UNKNOWN, TRACE_SPAN_TYPE_LLM, TRACE_SPAN_TYPE_RETRIEVER, TRACE_SPAN_TYPE_TOOL optional
Example: TRACE_SPAN_TYPE_UNKNOWN

Types of spans in a trace

ground_truth string optional
Example: example string

The ground truth for the prompt.

input string optional
Example: example string
input_tokens string (uint64) optional
Example: 12345

The number of input tokens used in the prompt.

output string optional
Example: example string
output_tokens string (uint64) optional
Example: 12345

The number of output tokens used in the prompt.

prompt_chunks array of object optional

The list of prompt chunks.

Show child properties
chunk_usage_pct number (double) optional
Example: 123

The usage percentage of the chunk.

chunk_used boolean optional
Example: true

Indicates if the chunk was used in the prompt.

index_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The index uuid (Knowledge Base) of the chunk.

source_name string optional
Example: example name

The source name for the chunk, e.g., the file name or document title.

text string optional
Example: example string

Text content of the chunk.

prompt_id integer (int64) optional
Example: 123

Prompt ID

prompt_level_metric_results array of object optional

The metric results for the prompt.

Show child properties
error_description string optional
Example: example string

Error description if the metric could not be calculated.

metric_name string optional
Example: example name

Metric name

metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
number_value number (double) optional
Example: 123

The value of the metric as a number.

reasoning string optional
Example: example string

Reasoning of the metric result.

string_value string optional
Example: example string

The value of the metric as a string.

trace_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The trace id for the prompt.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "prompt": {
    "evaluation_trace_spans": [],
    "ground_truth": "example string",
    "input": "example string",
    "input_tokens": "12345",
    "output": "example string",
    "output_tokens": "12345",
    "prompt_chunks": [],
    "prompt_id": 123,
    "prompt_level_metric_results": [],
    "trace_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Evaluation Test Cases

/v2/gen-ai/evaluation_test_cases
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all evaluation test cases, send a GET request to /v2/gen-ai/evaluation_test_cases.

Request: /v2/gen-ai/evaluation_test_cases
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
evaluation_test_cases array of object optional

Alternative way of authentication for internal usage only - should not be exposed to public api

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time created at.

dataset_name string optional
Example: example name

Name of the dataset.

dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the dataset.

file_size string (uint64) optional
Example: 12345

The size of the dataset uploaded file in bytes.

has_ground_truth boolean optional
Example: true

Does the dataset have a ground truth column?

row_count integer (int64) optional
Example: 123

Number of rows in the dataset.

dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Show child properties
category string (enum) optional
Example: METRIC_CATEGORY_UNSPECIFIED
description string optional
Example: example string
inverted boolean optional
Example: true

If true, the metric is inverted, meaning that a lower value is better.

is_metric_goal boolean optional
Example: true
metric_name string optional
Example: example name
metric_rank integer (int64) optional
Example: 123
metric_type string, one of: METRIC_TYPE_UNSPECIFIED, METRIC_TYPE_GENERAL_QUALITY, METRIC_TYPE_RAG_AND_TOOL optional
Example: METRIC_TYPE_UNSPECIFIED
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
range_max number (float) optional
Example: 123

The maximum value for the metric.

range_min number (float) optional
Example: 123

The minimum value for the metric.

name string optional
Example: example name
star_metric object optional
Show child properties
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
name string optional
Example: example name
success_threshold number (float) optional
Example: 123

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

success_threshold_pct integer (int32) optional
Example: 123

The success threshold for the star metric. This is a percentage value between 0 and 100.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "evaluation_test_cases": [
    {
      "archived_at": "2023-01-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by_user_email": "[email protected]",
      "created_by_user_id": "12345",
      "dataset_name": "example name",
      "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "description": "example string",
      "latest_version_number_of_runs": 123,
      "metrics": [],
      "name": "example name",
      "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "total_runs": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "updated_by_user_email": "[email protected]",
      "updated_by_user_id": "12345",
      "version": 123
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create Evaluation Test Case.

/v2/gen-ai/evaluation_test_cases
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create an evaluation test-case send a POST request to /v2/gen-ai/evaluation_test_cases.

Request Body: application/json

agent_workspace_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Dataset against which the test‑case is executed.

description string optional
Example: example string

Description of the test case.

metrics array of string optional
Example: ["example string"]

Full metric list to use for evaluation test case.

name string optional
Example: example name

Name of the test case.

star_metric object optional
Show child properties
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
name string optional
Example: example name
success_threshold number (float) optional
Example: 123

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

success_threshold_pct integer (int32) optional
Example: 123

The success threshold for the star metric. This is a percentage value between 0 and 100.

workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The workspace uuid.

Request: /v2/gen-ai/evaluation_test_cases
Content type application/json 
{
  "agent_workspace_name": "example name",
  "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "description": "example string",
  "metrics": [
    "example string"
  ],
  "name": "example name",
  "star_metric": {
    "metric_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "example name",
    "success_threshold": 123,
    "success_threshold_pct": 123
  },
  "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases" \
  -d '{
    "name": "Test Case",
    "description": "Description of the test case",
    "dataset_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "metrics": ["1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "2b418231-b7d6-11ef-bf8f-4e013e2ddde4"],
    "star_metric": {
      "metric_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
      "name": "Retrieved chunk usage",
      "success_threshold_pct": 80
    },
    "workspace_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Test‑case UUID.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Evaluation Runs by Test Case

/v2/gen-ai/evaluation_test_cases/{evaluation_test_case_uuid}/evaluation_runs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all evaluation runs by test case, send a GET request to /v2/gen-ai/evaluation_test_cases/{evaluation_test_case_uuid}/evaluation_runs.

Path Parameters

evaluation_test_case_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Evaluation run UUID.

Query Parameters

evaluation_test_case_version integer optional
Example: 1

Version of the test case.

Request: /v2/gen-ai/evaluation_test_cases/{evaluation_test_case_uuid}/evaluation_runs
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/evaluation_runs"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
evaluation_runs array of object optional

List of evaluation runs.

Show child properties
agent_deleted boolean optional
Example: true

Whether agent is deleted

agent_deployment_name string optional
Example: example name

The agent deployment name

agent_name string optional
Example: example name

Agent name

agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent UUID.

agent_version_hash string optional
Example: example string

Version hash

agent_workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent workspace uuid

created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
error_description string optional
Example: example string

The error description

evaluation_run_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Evaluation run UUID.

evaluation_test_case_workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Evaluation test case workspace uuid

finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Run end time.

pass_status boolean optional
Example: true

The pass status of the evaluation run based on the star metric.

queued_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Run queued time.

run_level_metric_results array of object optional
Show child properties
error_description string optional
Example: example string

Error description if the metric could not be calculated.

metric_name string optional
Example: example name

Metric name

metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
number_value number (double) optional
Example: 123

The value of the metric as a number.

reasoning string optional
Example: example string

Reasoning of the metric result.

string_value string optional
Example: example string

The value of the metric as a string.

run_name string optional
Example: example name

Run name.

star_metric_result object optional
Show child properties
error_description string optional
Example: example string

Error description if the metric could not be calculated.

metric_name string optional
Example: example name

Metric name

metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
number_value number (double) optional
Example: 123

The value of the metric as a number.

reasoning string optional
Example: example string

Reasoning of the metric result.

string_value string optional
Example: example string

The value of the metric as a string.

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Run start time.

status string (enum) optional
Example: EVALUATION_RUN_STATUS_UNSPECIFIED

Evaluation Run Statuses

test_case_description string optional
Example: example string

Test case description.

test_case_name string optional
Example: example name

Test case name.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Test-case UUID.

test_case_version integer (int64) optional
Example: 123

Test-case-version.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "evaluation_runs": [
    {
      "agent_deleted": true,
      "agent_deployment_name": "example name",
      "agent_name": "example name",
      "agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "agent_version_hash": "example string",
      "agent_workspace_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_by_user_email": "[email protected]",
      "created_by_user_id": "12345",
      "error_description": "example string",
      "evaluation_run_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "evaluation_test_case_workspace_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "finished_at": "2023-01-01T00:00:00Z",
      "pass_status": true,
      "queued_at": "2023-01-01T00:00:00Z",
      "run_level_metric_results": [],
      "run_name": "example name",
      "started_at": "2023-01-01T00:00:00Z",
      "status": "EVALUATION_RUN_STATUS_UNSPECIFIED",
      "test_case_description": "example string",
      "test_case_name": "example name",
      "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "test_case_version": 123
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Information About an Existing Evaluation Test Case

/v2/gen-ai/evaluation_test_cases/{test_case_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To retrive information about an existing evaluation test case, send a GET request to /v2/gen-ai/evaluation_test_case/{test_case_uuid}.

Path Parameters

test_case_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

The test case uuid to retrieve.

Query Parameters

evaluation_test_case_version integer optional
Example: 1

Version of the test case.

Request: /v2/gen-ai/evaluation_test_cases/{test_case_uuid}
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases/9758a232-b351-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
evaluation_test_case object optional
Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time created at.

dataset_name string optional
Example: example name

Name of the dataset.

dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the dataset.

file_size string (uint64) optional
Example: 12345

The size of the dataset uploaded file in bytes.

has_ground_truth boolean optional
Example: true

Does the dataset have a ground truth column?

row_count integer (int64) optional
Example: 123

Number of rows in the dataset.

dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Show child properties
category string (enum) optional
Example: METRIC_CATEGORY_UNSPECIFIED
description string optional
Example: example string
inverted boolean optional
Example: true

If true, the metric is inverted, meaning that a lower value is better.

is_metric_goal boolean optional
Example: true
metric_name string optional
Example: example name
metric_rank integer (int64) optional
Example: 123
metric_type string, one of: METRIC_TYPE_UNSPECIFIED, METRIC_TYPE_GENERAL_QUALITY, METRIC_TYPE_RAG_AND_TOOL optional
Example: METRIC_TYPE_UNSPECIFIED
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
range_max number (float) optional
Example: 123

The maximum value for the metric.

range_min number (float) optional
Example: 123

The minimum value for the metric.

name string optional
Example: example name
star_metric object optional
Show child properties
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
name string optional
Example: example name
success_threshold number (float) optional
Example: 123

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

success_threshold_pct integer (int32) optional
Example: 123

The success threshold for the star metric. This is a percentage value between 0 and 100.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "evaluation_test_case": {
    "archived_at": "2023-01-01T00:00:00Z",
    "created_at": "2023-01-01T00:00:00Z",
    "created_by_user_email": "[email protected]",
    "created_by_user_id": "12345",
    "dataset": {
      "created_at": "2023-01-01T00:00:00Z",
      "dataset_name": "example name",
      "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "file_size": "12345",
      "has_ground_truth": true,
      "row_count": 123
    },
    "dataset_name": "example name",
    "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "description": "example string",
    "latest_version_number_of_runs": 123,
    "metrics": [],
    "name": "example name",
    "star_metric": {
      "metric_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "name": "example name",
      "success_threshold": 123,
      "success_threshold_pct": 123
    },
    "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "total_runs": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "updated_by_user_email": "[email protected]",
    "updated_by_user_id": "12345",
    "version": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update an Evaluation Test Case.

/v2/gen-ai/evaluation_test_cases/{test_case_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update an evaluation test-case send a PUT request to /v2/gen-ai/evaluation_test_cases/{test_case_uuid}.

Path Parameters

test_case_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Test-case UUID to update

Request Body: application/json

dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Dataset against which the test‑case is executed.

description string optional
Example: example string

Description of the test case.

metrics object optional
Show child properties
metric_uuids array of string optional
Example: ["example string"]
name string optional
Example: example name

Name of the test case.

star_metric object optional
Show child properties
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
name string optional
Example: example name
success_threshold number (float) optional
Example: 123

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

success_threshold_pct integer (int32) optional
Example: 123

The success threshold for the star metric. This is a percentage value between 0 and 100.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Test-case UUID to update

Request: /v2/gen-ai/evaluation_test_cases/{test_case_uuid}
Content type application/json 
{
  "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "description": "example string",
  "metrics": {
    "metric_uuids": [
      "example string"
    ]
  },
  "name": "example name",
  "star_metric": {
    "metric_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "example name",
    "success_threshold": 123,
    "success_threshold_pct": 123
  },
  "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases/e51dba65-cf7a-11ef-bf8f-4e013e2ddde4" \
  -d '{
    "test_case_uuid": "e51dba65-cf7a-11ef-bf8f-4e013e2ddde4",
    "name": "Updated Test Case",
    "description": "Updated description of the test case",
    "dataset_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "metrics": ["1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "2b418231-b7d6-11ef-bf8f-4e013e2ddde4"],
    "star_metric": {
      "metric_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
      "name": "Retrieved chunk usage",
      "success_threshold_pct": 80
    }
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
version integer (int32) optional
Example: 123

The new verson of the test case.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "version": 123
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Indexing Jobs for a Knowledge Base

/v2/gen-ai/indexing_jobs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all indexing jobs for a knowledge base, send a GET request to /v2/gen-ai/indexing_jobs.

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/indexing_jobs
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/indexing_jobs"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
jobs array of object optional

The indexing jobs

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "jobs": [
    {
      "completed_datasources": 123,
      "created_at": "2023-01-01T00:00:00Z",
      "data_source_jobs": [],
      "data_source_uuids": [
        "example string"
      ],
      "finished_at": "2023-01-01T00:00:00Z",
      "is_report_available": true,
      "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "phase": "BATCH_JOB_PHASE_UNKNOWN",
      "started_at": "2023-01-01T00:00:00Z",
      "status": "INDEX_JOB_STATUS_UNKNOWN",
      "tokens": 123,
      "total_datasources": 123,
      "total_tokens": "12345",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Start Indexing Job for a Knowledge Base

/v2/gen-ai/indexing_jobs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To start an indexing job for a knowledge base, send a POST request to /v2/gen-ai/indexing_jobs.

Request Body: application/json

data_source_uuids array of string optional
Example: ["example string"]

List of data source ids to index, if none are provided, all data sources will be indexed

knowledge_base_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Knowledge base id

Request: /v2/gen-ai/indexing_jobs
Content type application/json 
{
  "data_source_uuids": [
    "example string"
  ],
  "knowledge_base_uuid": "\"12345678-1234-1234-1234-123456789012\""
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/indexing_jobs" \
  -d '{
    "knowledge_base_uuid": "9758a232-b351-11ef-bf8f-4e013e2ddde4",
    "data_source_uuids": [
      "9a825ee0-bbb1-11ef-bf8f-4e013e2ddde4"
    ]
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "job": {
    "completed_datasources": 123,
    "created_at": "2023-01-01T00:00:00Z",
    "data_source_jobs": [],
    "data_source_uuids": [
      "example string"
    ],
    "finished_at": "2023-01-01T00:00:00Z",
    "is_report_available": true,
    "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "phase": "BATCH_JOB_PHASE_UNKNOWN",
    "started_at": "2023-01-01T00:00:00Z",
    "status": "INDEX_JOB_STATUS_UNKNOWN",
    "tokens": 123,
    "total_datasources": 123,
    "total_tokens": "12345",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Data Sources for Indexing Job for a Knowledge Base

/v2/gen-ai/indexing_jobs/{indexing_job_uuid}/data_sources
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all datasources for an indexing job, send a GET request to /v2/gen-ai/indexing_jobs/{indexing_job_uuid}/data_sources.

Path Parameters

indexing_job_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Uuid of the indexing job

Request: /v2/gen-ai/indexing_jobs/{indexing_job_uuid}/data_sources
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/indexing_jobs/9758a232-b351-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
indexed_data_sources array of object optional
Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "indexed_data_sources": [
    {
      "completed_at": "2023-01-01T00:00:00Z",
      "data_source_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "error_details": "example string",
      "error_msg": "example string",
      "failed_item_count": "12345",
      "indexed_file_count": "12345",
      "indexed_item_count": "12345",
      "removed_item_count": "12345",
      "skipped_item_count": "12345",
      "started_at": "2023-01-01T00:00:00Z",
      "status": "DATA_SOURCE_STATUS_UNKNOWN",
      "total_bytes": "12345",
      "total_bytes_indexed": "12345",
      "total_file_count": "12345"
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Get Signed URL for Indexing Job Details

/v2/gen-ai/indexing_jobs/{indexing_job_uuid}/details_signed_url
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To get a signed URL for indexing job details, send a GET request to /v2/gen-ai/indexing_jobs/{uuid}/details_signed_url.

Path Parameters

indexing_job_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

The uuid of the indexing job

Request: /v2/gen-ai/indexing_jobs/{indexing_job_uuid}/details_signed_url
curl --location --request GET 'https://api.digitalocean.com/v2/gen-ai/indexing_jobs/6b090372-a8c3-11f0-b542-ca68c578b04b/details_signed_url' \
--header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' \
--header 'Content-Type: application/json'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
signed_url string optional
Example: example string

The signed url for downloading the indexing job details

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "signed_url": "example string"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Status of Indexing Job for a Knowledge Base

/v2/gen-ai/indexing_jobs/{uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To get status of an indexing Job for a knowledge base, send a GET request to /v2/gen-ai/indexing_jobs/{uuid}.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Indexing job id

Request: /v2/gen-ai/indexing_jobs/{uuid}
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/indexing_jobs/9758a232-b351-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "job": {
    "completed_datasources": 123,
    "created_at": "2023-01-01T00:00:00Z",
    "data_source_jobs": [],
    "data_source_uuids": [
      "example string"
    ],
    "finished_at": "2023-01-01T00:00:00Z",
    "is_report_available": true,
    "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "phase": "BATCH_JOB_PHASE_UNKNOWN",
    "started_at": "2023-01-01T00:00:00Z",
    "status": "INDEX_JOB_STATUS_UNKNOWN",
    "tokens": 123,
    "total_datasources": 123,
    "total_tokens": "12345",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Cancel Indexing Job for a Knowledge Base

/v2/gen-ai/indexing_jobs/{uuid}/cancel
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To cancel an indexing job for a knowledge base, send a PUT request to /v2/gen-ai/indexing_jobs/{uuid}/cancel.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

A unique identifier for an indexing job.

Request Body: application/json

uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

A unique identifier for an indexing job.

Request: /v2/gen-ai/indexing_jobs/{uuid}/cancel
Content type application/json 
{
  "uuid": "\"12345678-1234-1234-1234-123456789012\""
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/indexing_jobs/79ca9798-cf7d-11ef-bf8f-4e013e2ddde4/cancel" \
  -d '{
    "uuid": "79ca9798-cf7d-11ef-bf8f-4e013e2ddde4"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "job": {
    "completed_datasources": 123,
    "created_at": "2023-01-01T00:00:00Z",
    "data_source_jobs": [],
    "data_source_uuids": [
      "example string"
    ],
    "finished_at": "2023-01-01T00:00:00Z",
    "is_report_available": true,
    "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "phase": "BATCH_JOB_PHASE_UNKNOWN",
    "started_at": "2023-01-01T00:00:00Z",
    "status": "INDEX_JOB_STATUS_UNKNOWN",
    "tokens": 123,
    "total_datasources": 123,
    "total_tokens": "12345",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Knowledge Bases

/v2/gen-ai/knowledge_bases
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all knowledge bases, send a GET request to /v2/gen-ai/knowledge_bases.

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/knowledge_bases
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
knowledge_bases array of object optional

The knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "knowledge_bases": [
    {
      "added_to_agent_at": "2023-01-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z",
      "database_id": "123e4567-e89b-12d3-a456-426614174000",
      "embedding_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "is_public": true,
      "name": "example name",
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "region": "example string",
      "tags": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "user_id": "12345",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create a Knowledge Base

/v2/gen-ai/knowledge_bases
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create a knowledge base, send a POST request to /v2/gen-ai/knowledge_bases.

Request Body: application/json

database_id string optional
Example: "12345678-1234-1234-1234-123456789012"

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.

datasources array of object optional

The data sources to use for this knowledge base. See Organize Data Sources for more information on data sources best practices.

Show child properties
aws_data_source object optional

AWS S3 Data Source

Show child properties
bucket_name string optional
Example: example name

Spaces bucket name

item_path string optional
Example: example string
key_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The AWS Key ID

region string optional
Example: example string

Region of bucket

secret_key string optional
Example: example string

The AWS Secret Key

bucket_name string optional
Example: example name

Deprecated, moved to data_source_details

bucket_region string optional
Example: example string

Deprecated, moved to data_source_details

chunking_algorithm string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional
Example: CHUNKING_ALGORITHM_SECTION_BASED

The chunking algorithm to use for processing data sources.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

chunking_options object optional

Configuration options for the chunking algorithm.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

Show child properties
child_chunk_size integer (int64) optional
Example: 350

Hierarchical options

max_chunk_size integer (int64) optional
Example: 750

Section_Based and Fixed_Length options

parent_chunk_size integer (int64) optional
Example: 1000

Hierarchical options

semantic_threshold number (float) optional
Example: 0.5

Semantic options

dropbox_data_source object optional

Dropbox Data Source

Show child properties
folder string optional
Example: example string
refresh_token string optional
Example: example string

Refresh token. you can obrain a refresh token by following the oauth2 flow. see /v2/gen-ai/oauth2/dropbox/tokens for reference.

file_upload_data_source object optional

File to upload as data source for knowledge base.

Show child properties
original_file_name string optional
Example: example name

The original file name

size_in_bytes string (uint64) optional
Example: 12345

The size of the file in bytes

stored_object_key string optional
Example: example string

The object key the file was stored as

google_drive_data_source object optional

Google Drive Data Source

Show child properties
folder_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
refresh_token string optional
Example: example string

Refresh token. you can obrain a refresh token by following the oauth2 flow. see /v2/gen-ai/oauth2/google/tokens for reference.

item_path string optional
Example: example string
spaces_data_source object optional

Spaces Bucket Data Source

Show child properties
bucket_name string optional
Example: example name

Spaces bucket name

item_path string optional
Example: example string
region string optional
Example: example string

Region of bucket

web_crawler_data_source object optional

WebCrawlerDataSource

Show child properties
base_url string optional
Example: example string

The base url to crawl.

crawling_option string (enum) optional
Example: UNKNOWN

Options for specifying how URLs found on pages should be handled.

  • UNKNOWN: Default unknown value
  • SCOPED: Only include the base URL.
  • PATH: Crawl the base URL and linked pages within the URL path.
  • DOMAIN: Crawl the base URL and linked pages within the same domain.
  • SUBDOMAINS: Crawl the base URL and linked pages for any subdomain.
  • SITEMAP: Crawl URLs discovered in the sitemap.
embed_media boolean optional
Example: true

Whether to ingest and index media (images, etc.) on web pages.

exclude_tags array of string optional
Example: ["example string"]

Declaring which tags to exclude in web pages while webcrawling

embedding_model_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Identifier for the embedding model.

name string optional
Example: "My Knowledge Base"

Name of the knowledge base.

project_id string optional
Example: "12345678-1234-1234-1234-123456789012"

Identifier of the DigitalOcean project this knowledge base will belong to.

region string optional
Example: "tor1"

The datacenter region to deploy the knowledge base in.

tags array of string optional
Example: ["example string"]

Tags to organize your knowledge base.

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

The VPC to deploy the knowledge base database in

Request: /v2/gen-ai/knowledge_bases
Content type application/json 
{
  "database_id": "\"12345678-1234-1234-1234-123456789012\"",
  "datasources": [
    {
      "bucket_name": "example name",
      "bucket_region": "example string",
      "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED",
      "item_path": "example string"
    }
  ],
  "embedding_model_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"My Knowledge Base\"",
  "project_id": "\"12345678-1234-1234-1234-123456789012\"",
  "region": "\"tor1\"",
  "tags": [
    "example string"
  ],
  "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\""
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases" \
  -d '{
    "name": "kb-api-create",
    "embedding_model_uuid": "05700391-7aa8-11ef-bf8f-4e013e2ddde4",
    "project_id": "37455431-84bd-4fa2-94cf-e8486f8f8c5e",
    "tags": [
      "tag1"
    ],
    "database_id": "abf1055a-745d-4c24-a1db-1959ea819264",
    "datasources": [
      {
          "spaces_data_source": {
              "bucket_name": "test-public-gen-ai",
              "region": "tor1"
            },
            "chunking_algorithm": "CHUNKING_ALGORITHM_HIERARCHICAL",
            "chunking_options": {
              "parent_chunk_size": 1000,
              "child_chunk_size": 350
            }
      },
      {
        "web_crawler_data_source": {
          "base_url": "https://example.com",
          "crawling_option": "SCOPED",
          "embed_media": false,
          "exclude_tags": ["nav","footer","header","aside","script","style","form","iframe", "noscript"]
        },
        "chunking_algorithm": "CHUNKING_ALGORITHM_SEMANTIC",
        "chunking_options": {
          "max_chunk_size": 500,
          "semantic_threshold": 0.6
        }
      },
      {
        "spaces_data_source": {
            "bucket_name": "test-public-gen-ai-2",
            "region": "tor1"
          },
          "chunking_algorithm": "CHUNKING_ALGORITHM_FIXED_LENGTH",
          "chunking_options": {
            "max_chunk_size": 400
          }
      },
    ],
    "region": "tor1",
    "vpc_uuid": "f7176e0b-8c5e-4e32-948e-79327e56225a"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
knowledge_base object optional

Knowledgebase Description

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "knowledge_base": {
    "added_to_agent_at": "2023-01-01T00:00:00Z",
    "created_at": "2023-01-01T00:00:00Z",
    "database_id": "123e4567-e89b-12d3-a456-426614174000",
    "embedding_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "is_public": true,
    "last_indexing_job": {
      "completed_datasources": 123,
      "created_at": "2023-01-01T00:00:00Z",
      "data_source_jobs": [],
      "data_source_uuids": [
        "example string"
      ],
      "finished_at": "2023-01-01T00:00:00Z",
      "is_report_available": true,
      "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "phase": "BATCH_JOB_PHASE_UNKNOWN",
      "started_at": "2023-01-01T00:00:00Z",
      "status": "INDEX_JOB_STATUS_UNKNOWN",
      "tokens": 123,
      "total_datasources": 123,
      "total_tokens": "12345",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "name": "example name",
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "region": "example string",
    "tags": [
      "example string"
    ],
    "updated_at": "2023-01-01T00:00:00Z",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create Presigned URLs for Data Source File Upload

/v2/gen-ai/knowledge_bases/data_sources/file_upload_presigned_urls
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create presigned URLs for knowledge base data source file upload, send a POST request to /v2/gen-ai/knowledge_bases/data_sources/file_upload_presigned_urls.

Request Body: application/json

files array of object optional

A list of files to generate presigned URLs for.

Show child properties
file_name string optional
Example: example name

Local filename

file_size string (int64) optional
Example: 12345

The size of the file in bytes.

Request: /v2/gen-ai/knowledge_bases/data_sources/file_upload_presigned_urls
Content type application/json 
{
  "files": [
    {
      "file_name": "example name",
      "file_size": "12345"
    }
  ]
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/data_sources/file_upload_presigned_urls" \
  -d '{
    "files": [{
      "file_name": "dataset.csv",
      "file_size": 2048
    }]
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
request_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The ID generated for the request for Presigned URLs.

uploads array of object optional

A list of generated presigned URLs and object keys, one per file.

Show child properties
expires_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The time the url expires at.

object_key string optional
Example: example string

The unique object key to store the file as.

original_file_name string optional
Example: example name

The original file name.

presigned_url string optional
Example: example string

The actual presigned URL the client can use to upload the file directly.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "uploads": [
    {
      "expires_at": "2023-01-01T00:00:00Z",
      "object_key": "example string",
      "original_file_name": "example name",
      "presigned_url": "example string"
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Data Sources for a Knowledge Base

/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all data sources for a knowledge base, send a GET request to /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources.

Path Parameters

knowledge_base_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Knowledge base id

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9758a232-b351-11ef-bf8f-4e013e2ddde4/data_sources"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
knowledge_base_data_sources array of object optional

The data sources

Show child properties
aws_data_source object optional

AWS S3 Data Source for Display

Show child properties
bucket_name string optional
Example: example name

Spaces bucket name

item_path string optional
Example: example string
region string optional
Example: example string

Region of bucket

bucket_name string optional
Example: example name

Name of storage bucket - Deprecated, moved to data_source_details

chunking_algorithm string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional
Example: CHUNKING_ALGORITHM_SECTION_BASED

The chunking algorithm to use for processing data sources.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

chunking_options object optional

Configuration options for the chunking algorithm.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

Show child properties
child_chunk_size integer (int64) optional
Example: 350

Hierarchical options

max_chunk_size integer (int64) optional
Example: 750

Section_Based and Fixed_Length options

parent_chunk_size integer (int64) optional
Example: 1000

Hierarchical options

semantic_threshold number (float) optional
Example: 0.5

Semantic options

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

dropbox_data_source object optional

Dropbox Data Source for Display

Show child properties
folder string optional
Example: example string
file_upload_data_source object optional

File to upload as data source for knowledge base.

Show child properties
original_file_name string optional
Example: example name

The original file name

size_in_bytes string (uint64) optional
Example: 12345

The size of the file in bytes

stored_object_key string optional
Example: example string

The object key the file was stored as

google_drive_data_source object optional

Google Drive Data Source for Display

Show child properties
folder_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
folder_name string optional
Example: example name

Name of the selected folder if available

item_path string optional
Example: example string

Path of folder or object in bucket - Deprecated, moved to data_source_details

last_datasource_indexing_job object optional
Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

region string optional
Example: example string

Region code - Deprecated, moved to data_source_details

spaces_data_source object optional

Spaces Bucket Data Source

Show child properties
bucket_name string optional
Example: example name

Spaces bucket name

item_path string optional
Example: example string
region string optional
Example: example string

Region of bucket

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of knowledge base

web_crawler_data_source object optional

WebCrawlerDataSource

Show child properties
base_url string optional
Example: example string

The base url to crawl.

crawling_option string (enum) optional
Example: UNKNOWN

Options for specifying how URLs found on pages should be handled.

  • UNKNOWN: Default unknown value
  • SCOPED: Only include the base URL.
  • PATH: Crawl the base URL and linked pages within the URL path.
  • DOMAIN: Crawl the base URL and linked pages within the same domain.
  • SUBDOMAINS: Crawl the base URL and linked pages for any subdomain.
  • SITEMAP: Crawl URLs discovered in the sitemap.
embed_media boolean optional
Example: true

Whether to ingest and index media (images, etc.) on web pages.

exclude_tags array of string optional
Example: ["example string"]

Declaring which tags to exclude in web pages while webcrawling

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "knowledge_base_data_sources": [
    {
      "bucket_name": "example name",
      "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED",
      "created_at": "2023-01-01T00:00:00Z",
      "item_path": "example string",
      "region": "example string",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Add Data Source to a Knowledge Base

/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To add a data source to a knowledge base, send a POST request to /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources.

Path Parameters

knowledge_base_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Knowledge base id

Request Body: application/json

aws_data_source object optional

AWS S3 Data Source

Show child properties
bucket_name string optional
Example: example name

Spaces bucket name

item_path string optional
Example: example string
key_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The AWS Key ID

region string optional
Example: example string

Region of bucket

secret_key string optional
Example: example string

The AWS Secret Key

chunking_algorithm string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional
Example: CHUNKING_ALGORITHM_SECTION_BASED

The chunking algorithm to use for processing data sources.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

chunking_options object optional

Configuration options for the chunking algorithm.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

Show child properties
child_chunk_size integer (int64) optional
Example: 350

Hierarchical options

max_chunk_size integer (int64) optional
Example: 750

Section_Based and Fixed_Length options

parent_chunk_size integer (int64) optional
Example: 1000

Hierarchical options

semantic_threshold number (float) optional
Example: 0.5

Semantic options

knowledge_base_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Knowledge base id

spaces_data_source object optional

Spaces Bucket Data Source

Show child properties
bucket_name string optional
Example: example name

Spaces bucket name

item_path string optional
Example: example string
region string optional
Example: example string

Region of bucket

web_crawler_data_source object optional

WebCrawlerDataSource

Show child properties
base_url string optional
Example: example string

The base url to crawl.

crawling_option string (enum) optional
Example: UNKNOWN

Options for specifying how URLs found on pages should be handled.

  • UNKNOWN: Default unknown value
  • SCOPED: Only include the base URL.
  • PATH: Crawl the base URL and linked pages within the URL path.
  • DOMAIN: Crawl the base URL and linked pages within the same domain.
  • SUBDOMAINS: Crawl the base URL and linked pages for any subdomain.
  • SITEMAP: Crawl URLs discovered in the sitemap.
embed_media boolean optional
Example: true

Whether to ingest and index media (images, etc.) on web pages.

exclude_tags array of string optional
Example: ["example string"]

Declaring which tags to exclude in web pages while webcrawling

Request: /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources
Content type application/json 
{
  "aws_data_source": {
    "bucket_name": "example name",
    "item_path": "example string",
    "key_id": "123e4567-e89b-12d3-a456-426614174000",
    "region": "example string",
    "secret_key": "example string"
  },
  "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED",
  "chunking_options": {
    "child_chunk_size": 350,
    "max_chunk_size": 750,
    "parent_chunk_size": 1000,
    "semantic_threshold": 0.5
  },
  "knowledge_base_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "spaces_data_source": {
    "bucket_name": "example name",
    "item_path": "example string",
    "region": "example string"
  },
  "web_crawler_data_source": {
    "base_url": "example string",
    "crawling_option": "UNKNOWN",
    "embed_media": true,
    "exclude_tags": [
      "example string"
    ]
  }
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/20cd8434-6ea1-11f0-bf8f-4e013e2ddde4/data_sources" \
  -d '{
"knowledge_base_uuid": "20cd8434-6ea1-11f0-bf8f-4e013e2ddde4",
"web_crawler_data_source": {
  "base_url": "https://example.com",
  "crawling_option": "SCOPED",
  "embed_media": false,
  "exclude_tags": ["nav","footer","header","aside","script","style","form","iframe", "noscript"]
},
"chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED",
"chunking_options": {
  "max_chunk_size": 500
}
}'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
knowledge_base_data_source object optional

Data Source configuration for Knowledge Bases

Show child properties
aws_data_source object optional

AWS S3 Data Source for Display

Show child properties
bucket_name string optional
Example: example name

Spaces bucket name

item_path string optional
Example: example string
region string optional
Example: example string

Region of bucket

bucket_name string optional
Example: example name

Name of storage bucket - Deprecated, moved to data_source_details

chunking_algorithm string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional
Example: CHUNKING_ALGORITHM_SECTION_BASED

The chunking algorithm to use for processing data sources.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

chunking_options object optional

Configuration options for the chunking algorithm.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

Show child properties
child_chunk_size integer (int64) optional
Example: 350

Hierarchical options

max_chunk_size integer (int64) optional
Example: 750

Section_Based and Fixed_Length options

parent_chunk_size integer (int64) optional
Example: 1000

Hierarchical options

semantic_threshold number (float) optional
Example: 0.5

Semantic options

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

dropbox_data_source object optional

Dropbox Data Source for Display

Show child properties
folder string optional
Example: example string
file_upload_data_source object optional

File to upload as data source for knowledge base.

Show child properties
original_file_name string optional
Example: example name

The original file name

size_in_bytes string (uint64) optional
Example: 12345

The size of the file in bytes

stored_object_key string optional
Example: example string

The object key the file was stored as

google_drive_data_source object optional

Google Drive Data Source for Display

Show child properties
folder_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
folder_name string optional
Example: example name

Name of the selected folder if available

item_path string optional
Example: example string

Path of folder or object in bucket - Deprecated, moved to data_source_details

last_datasource_indexing_job object optional
Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

region string optional
Example: example string

Region code - Deprecated, moved to data_source_details

spaces_data_source object optional

Spaces Bucket Data Source

Show child properties
bucket_name string optional
Example: example name

Spaces bucket name

item_path string optional
Example: example string
region string optional
Example: example string

Region of bucket

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of knowledge base

web_crawler_data_source object optional

WebCrawlerDataSource

Show child properties
base_url string optional
Example: example string

The base url to crawl.

crawling_option string (enum) optional
Example: UNKNOWN

Options for specifying how URLs found on pages should be handled.

  • UNKNOWN: Default unknown value
  • SCOPED: Only include the base URL.
  • PATH: Crawl the base URL and linked pages within the URL path.
  • DOMAIN: Crawl the base URL and linked pages within the same domain.
  • SUBDOMAINS: Crawl the base URL and linked pages for any subdomain.
  • SITEMAP: Crawl URLs discovered in the sitemap.
embed_media boolean optional
Example: true

Whether to ingest and index media (images, etc.) on web pages.

exclude_tags array of string optional
Example: ["example string"]

Declaring which tags to exclude in web pages while webcrawling

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "knowledge_base_data_source": {
    "aws_data_source": {
      "bucket_name": "example name",
      "item_path": "example string",
      "region": "example string"
    },
    "bucket_name": "example name",
    "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED",
    "chunking_options": {
      "child_chunk_size": 350,
      "max_chunk_size": 750,
      "parent_chunk_size": 1000,
      "semantic_threshold": 0.5
    },
    "created_at": "2023-01-01T00:00:00Z",
    "dropbox_data_source": {
      "folder": "example string"
    },
    "file_upload_data_source": {
      "original_file_name": "example name",
      "size_in_bytes": "12345",
      "stored_object_key": "example string"
    },
    "google_drive_data_source": {
      "folder_id": "123e4567-e89b-12d3-a456-426614174000",
      "folder_name": "example name"
    },
    "item_path": "example string",
    "last_datasource_indexing_job": {
      "completed_at": "2023-01-01T00:00:00Z",
      "data_source_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "error_details": "example string",
      "error_msg": "example string",
      "failed_item_count": "12345",
      "indexed_file_count": "12345",
      "indexed_item_count": "12345",
      "removed_item_count": "12345",
      "skipped_item_count": "12345",
      "started_at": "2023-01-01T00:00:00Z",
      "status": "DATA_SOURCE_STATUS_UNKNOWN",
      "total_bytes": "12345",
      "total_bytes_indexed": "12345",
      "total_file_count": "12345"
    },
    "region": "example string",
    "spaces_data_source": {
      "bucket_name": "example name",
      "item_path": "example string",
      "region": "example string"
    },
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "web_crawler_data_source": {
      "base_url": "example string",
      "crawling_option": "UNKNOWN",
      "embed_media": true,
      "exclude_tags": [
        "example string"
      ]
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update Data Source options

/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources/{data_source_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update a data source (e.g. chunking options), send a PUT request to /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources/{data_source_uuid}.

Path Parameters

knowledge_base_uuid string required
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge Base ID (Path Parameter)

data_source_uuid string required
Example: 123e4567-e89b-12d3-a456-426614174000

Data Source ID (Path Parameter)

Request Body: application/json

chunking_algorithm string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional
Example: CHUNKING_ALGORITHM_SECTION_BASED

The chunking algorithm to use for processing data sources.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

chunking_options object optional

Configuration options for the chunking algorithm.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

Show child properties
child_chunk_size integer (int64) optional
Example: 350

Hierarchical options

max_chunk_size integer (int64) optional
Example: 750

Section_Based and Fixed_Length options

parent_chunk_size integer (int64) optional
Example: 1000

Hierarchical options

semantic_threshold number (float) optional
Example: 0.5

Semantic options

data_source_uuid string optional
Example: 98765432-1234-1234-1234-123456789012

Data Source ID (Path Parameter)

knowledge_base_uuid string optional
Example: 12345678-1234-1234-1234-123456789012

Knowledge Base ID (Path Parameter)

Request: /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources/{data_source_uuid}
Content type application/json 
{
  "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED",
  "chunking_options": {
    "child_chunk_size": 350,
    "max_chunk_size": 750,
    "parent_chunk_size": 1000,
    "semantic_threshold": 0.5
  },
  "data_source_uuid": "98765432-1234-1234-1234-123456789012",
  "knowledge_base_uuid": "12345678-1234-1234-1234-123456789012"
}
curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/12345678-1234-1234-1234-123456789012/data_sources/98765432-1234-1234-1234-123456789012" \
  -d '{
    "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED",
    "chunking_options": {
      "max_chunk_size": 500
    }
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
knowledge_base_data_source object optional

Data Source configuration for Knowledge Bases

Show child properties
aws_data_source object optional

AWS S3 Data Source for Display

Show child properties
bucket_name string optional
Example: example name

Spaces bucket name

item_path string optional
Example: example string
region string optional
Example: example string

Region of bucket

bucket_name string optional
Example: example name

Name of storage bucket - Deprecated, moved to data_source_details

chunking_algorithm string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional
Example: CHUNKING_ALGORITHM_SECTION_BASED

The chunking algorithm to use for processing data sources.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

chunking_options object optional

Configuration options for the chunking algorithm.

Note: This feature requires enabling the knowledgebase enhancements feature preview flag.

Show child properties
child_chunk_size integer (int64) optional
Example: 350

Hierarchical options

max_chunk_size integer (int64) optional
Example: 750

Section_Based and Fixed_Length options

parent_chunk_size integer (int64) optional
Example: 1000

Hierarchical options

semantic_threshold number (float) optional
Example: 0.5

Semantic options

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

dropbox_data_source object optional

Dropbox Data Source for Display

Show child properties
folder string optional
Example: example string
file_upload_data_source object optional

File to upload as data source for knowledge base.

Show child properties
original_file_name string optional
Example: example name

The original file name

size_in_bytes string (uint64) optional
Example: 12345

The size of the file in bytes

stored_object_key string optional
Example: example string

The object key the file was stored as

google_drive_data_source object optional

Google Drive Data Source for Display

Show child properties
folder_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
folder_name string optional
Example: example name

Name of the selected folder if available

item_path string optional
Example: example string

Path of folder or object in bucket - Deprecated, moved to data_source_details

last_datasource_indexing_job object optional
Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

region string optional
Example: example string

Region code - Deprecated, moved to data_source_details

spaces_data_source object optional

Spaces Bucket Data Source

Show child properties
bucket_name string optional
Example: example name

Spaces bucket name

item_path string optional
Example: example string
region string optional
Example: example string

Region of bucket

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of knowledge base

web_crawler_data_source object optional

WebCrawlerDataSource

Show child properties
base_url string optional
Example: example string

The base url to crawl.

crawling_option string (enum) optional
Example: UNKNOWN

Options for specifying how URLs found on pages should be handled.

  • UNKNOWN: Default unknown value
  • SCOPED: Only include the base URL.
  • PATH: Crawl the base URL and linked pages within the URL path.
  • DOMAIN: Crawl the base URL and linked pages within the same domain.
  • SUBDOMAINS: Crawl the base URL and linked pages for any subdomain.
  • SITEMAP: Crawl URLs discovered in the sitemap.
embed_media boolean optional
Example: true

Whether to ingest and index media (images, etc.) on web pages.

exclude_tags array of string optional
Example: ["example string"]

Declaring which tags to exclude in web pages while webcrawling

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "knowledge_base_data_source": {
    "aws_data_source": {
      "bucket_name": "example name",
      "item_path": "example string",
      "region": "example string"
    },
    "bucket_name": "example name",
    "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED",
    "chunking_options": {
      "child_chunk_size": 350,
      "max_chunk_size": 750,
      "parent_chunk_size": 1000,
      "semantic_threshold": 0.5
    },
    "created_at": "2023-01-01T00:00:00Z",
    "dropbox_data_source": {
      "folder": "example string"
    },
    "file_upload_data_source": {
      "original_file_name": "example name",
      "size_in_bytes": "12345",
      "stored_object_key": "example string"
    },
    "google_drive_data_source": {
      "folder_id": "123e4567-e89b-12d3-a456-426614174000",
      "folder_name": "example name"
    },
    "item_path": "example string",
    "last_datasource_indexing_job": {
      "completed_at": "2023-01-01T00:00:00Z",
      "data_source_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "error_details": "example string",
      "error_msg": "example string",
      "failed_item_count": "12345",
      "indexed_file_count": "12345",
      "indexed_item_count": "12345",
      "removed_item_count": "12345",
      "skipped_item_count": "12345",
      "started_at": "2023-01-01T00:00:00Z",
      "status": "DATA_SOURCE_STATUS_UNKNOWN",
      "total_bytes": "12345",
      "total_bytes_indexed": "12345",
      "total_file_count": "12345"
    },
    "region": "example string",
    "spaces_data_source": {
      "bucket_name": "example name",
      "item_path": "example string",
      "region": "example string"
    },
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "web_crawler_data_source": {
      "base_url": "example string",
      "crawling_option": "UNKNOWN",
      "embed_media": true,
      "exclude_tags": [
        "example string"
      ]
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a Data Source from a Knowledge Base

/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources/{data_source_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete a data source from a knowledge base, send a DELETE request to /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources/{data_source_uuid}.

Path Parameters

knowledge_base_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Knowledge base id

data_source_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Data source id

Request: /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources/{data_source_uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4/data_sources/bd2a2db5-b8b0-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Data source id

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "data_source_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Indexing Jobs for a Knowledge Base

/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/indexing_jobs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list latest 15 indexing jobs for a knowledge base, send a GET request to /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/indexing_jobs.

Path Parameters

knowledge_base_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Knowledge base uuid in string

Request: /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/indexing_jobs
curl --location --request GET 'https://api.digitalocean.com/v2/gen-ai/knowledge_bases/1139121f-a860-11f0-b542-ca68c578b04b/indexing_jobs' \
--header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' \
--header 'Content-Type: application/json'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
jobs array of object optional

The indexing jobs

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "jobs": [
    {
      "completed_datasources": 123,
      "created_at": "2023-01-01T00:00:00Z",
      "data_source_jobs": [],
      "data_source_uuids": [
        "example string"
      ],
      "finished_at": "2023-01-01T00:00:00Z",
      "is_report_available": true,
      "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "phase": "BATCH_JOB_PHASE_UNKNOWN",
      "started_at": "2023-01-01T00:00:00Z",
      "status": "INDEX_JOB_STATUS_UNKNOWN",
      "tokens": 123,
      "total_datasources": 123,
      "total_tokens": "12345",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Information About an Existing Knowledge Base

/v2/gen-ai/knowledge_bases/{uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To retrive information about an existing knowledge base, send a GET request to /v2/gen-ai/knowledge_bases/{uuid}.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Knowledge base id

Request: /v2/gen-ai/knowledge_bases/{uuid}
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9758a232-b351-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
database_status string (enum) optional
Example: CREATING
knowledge_base object optional

Knowledgebase Description

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "database_status": "CREATING",
  "knowledge_base": {
    "added_to_agent_at": "2023-01-01T00:00:00Z",
    "created_at": "2023-01-01T00:00:00Z",
    "database_id": "123e4567-e89b-12d3-a456-426614174000",
    "embedding_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "is_public": true,
    "last_indexing_job": {
      "completed_datasources": 123,
      "created_at": "2023-01-01T00:00:00Z",
      "data_source_jobs": [],
      "data_source_uuids": [
        "example string"
      ],
      "finished_at": "2023-01-01T00:00:00Z",
      "is_report_available": true,
      "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "phase": "BATCH_JOB_PHASE_UNKNOWN",
      "started_at": "2023-01-01T00:00:00Z",
      "status": "INDEX_JOB_STATUS_UNKNOWN",
      "tokens": 123,
      "total_datasources": 123,
      "total_tokens": "12345",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "name": "example name",
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "region": "example string",
    "tags": [
      "example string"
    ],
    "updated_at": "2023-01-01T00:00:00Z",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update a Knowledge Base

/v2/gen-ai/knowledge_bases/{uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update a knowledge base, send a PUT request to /v2/gen-ai/knowledge_bases/{uuid}.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Knowledge base id

Request Body: application/json

database_id string optional
Example: "12345678-1234-1234-1234-123456789012"

The id of the DigitalOcean database this knowledge base will use, optiona.

embedding_model_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Identifier for the foundation model.

name string optional
Example: "My Knowledge Base"

Knowledge base name

project_id string optional
Example: "12345678-1234-1234-1234-123456789012"

The id of the DigitalOcean project this knowledge base will belong to

tags array of string optional
Example: ["example string"]

Tags to organize your knowledge base.

uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Knowledge base id

Request: /v2/gen-ai/knowledge_bases/{uuid}
Content type application/json 
{
  "database_id": "\"12345678-1234-1234-1234-123456789012\"",
  "embedding_model_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"My Knowledge Base\"",
  "project_id": "\"12345678-1234-1234-1234-123456789012\"",
  "tags": [
    "example string"
  ],
  "uuid": "\"12345678-1234-1234-1234-123456789012\""
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/e51dba65-cf7a-11ef-bf8f-4e013e2ddde4" \
  -d '{
    "uuid": "e51dba65-cf7a-11ef-bf8f-4e013e2ddde4",
    "name": "kb-api-rename"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
knowledge_base object optional

Knowledgebase Description

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Show child properties
completed_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source completed indexing

data_source_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the indexed data source

error_details string optional
Example: example string

A detailed error description

error_msg string optional
Example: example string

A string code provinding a hint which part of the system experienced an error

failed_item_count string (uint64) optional
Example: 12345

Total count of files that have failed

indexed_file_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

indexed_item_count string (uint64) optional
Example: 12345

Total count of files that have been indexed

removed_item_count string (uint64) optional
Example: 12345

Total count of files that have been removed

skipped_item_count string (uint64) optional
Example: 12345

Total count of files that have been skipped

started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when data source started indexing

status string (enum) optional
Example: DATA_SOURCE_STATUS_UNKNOWN
total_bytes string (uint64) optional
Example: 12345

Total size of files in data source in bytes

total_bytes_indexed string (uint64) optional
Example: 12345

Total size of files in data source in bytes that have been indexed

total_file_count string (uint64) optional
Example: 12345

Total file count in the data source

data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "knowledge_base": {
    "added_to_agent_at": "2023-01-01T00:00:00Z",
    "created_at": "2023-01-01T00:00:00Z",
    "database_id": "123e4567-e89b-12d3-a456-426614174000",
    "embedding_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "is_public": true,
    "last_indexing_job": {
      "completed_datasources": 123,
      "created_at": "2023-01-01T00:00:00Z",
      "data_source_jobs": [],
      "data_source_uuids": [
        "example string"
      ],
      "finished_at": "2023-01-01T00:00:00Z",
      "is_report_available": true,
      "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "phase": "BATCH_JOB_PHASE_UNKNOWN",
      "started_at": "2023-01-01T00:00:00Z",
      "status": "INDEX_JOB_STATUS_UNKNOWN",
      "tokens": 123,
      "total_datasources": 123,
      "total_tokens": "12345",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "name": "example name",
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "region": "example string",
    "tags": [
      "example string"
    ],
    "updated_at": "2023-01-01T00:00:00Z",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a Knowledge Base

/v2/gen-ai/knowledge_bases/{uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete a knowledge base, send a DELETE request to /v2/gen-ai/knowledge_bases/{uuid}.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Knowledge base id

Request: /v2/gen-ai/knowledge_bases/{uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/8241f44e-b0da-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

The id of the deleted knowledge base

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Available Models

/v2/gen-ai/models
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all models, send a GET request to /v2/gen-ai/models.

Query Parameters

usecases array of string (enum) optional
Example: ["MODEL_USECASE_UNKNOWN"]

Include only models defined for the listed usecases.

  • MODEL_USECASE_UNKNOWN: The use case of the model is unknown
  • MODEL_USECASE_AGENT: The model maybe used in an agent
  • MODEL_USECASE_FINETUNED: The model maybe used for fine tuning
  • MODEL_USECASE_KNOWLEDGEBASE: The model maybe used for knowledge bases (embedding models)
  • MODEL_USECASE_GUARDRAIL: The model maybe used for guardrails
  • MODEL_USECASE_REASONING: The model usecase for reasoning
  • MODEL_USECASE_SERVERLESS: The model usecase for serverless inference
public_only boolean optional
Example: true

Only include models that are publicly available.

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/models
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/models"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

models array of object optional

The models

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2021-01-01T00:00:00Z

Creation date / time

id string optional
Example: llama3.3-70b-instruct

Human-readable model identifier

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

name string optional
Example: Llama 3.3 Instruct (70B)

Display name of the model

parent_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Unique id of the model, this model is based on

updated_at string (date-time) optional
Example: 2021-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: https://example.com/model.zip

Download url

uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  },
  "models": [
    {
      "created_at": "2021-01-01T00:00:00Z",
      "id": "llama3.3-70b-instruct",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "name": "Llama 3.3 Instruct (70B)",
      "parent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
      "updated_at": "2021-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "https://example.com/model.zip",
      "uuid": "\"12345678-1234-1234-1234-123456789012\""
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Model API Keys

/v2/gen-ai/models/api_keys
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all model API keys, send a GET request to /v2/gen-ai/models/api_keys.

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/models/api_keys
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/models/api_keys"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_infos": [
    {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "secret_key": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create a Model API Key

/v2/gen-ai/models/api_keys
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create a model API key, send a POST request to /v2/gen-ai/models/api_keys.

Request Body: application/json

name string optional
Example: Production Key

A human friendly name to identify the key

Request: /v2/gen-ai/models/api_keys
Content type application/json 
{
  "name": "Production Key"
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/models/api_keys" \
  -d '{
    "name": "test-key"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Model API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "secret_key": "example string",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update API Key for a Model

/v2/gen-ai/models/api_keys/{api_key_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update a model API key, send a PUT request to /v2/gen-ai/models/api_keys/{api_key_uuid}.

Path Parameters

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key ID

Request Body: application/json

api_key_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

API key ID

name string optional
Example: "Production Key"

Name

Request: /v2/gen-ai/models/api_keys/{api_key_uuid}
Content type application/json 
{
  "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"Production Key\""
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/models/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \
  -d '{
    "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4",
    "name": "test-key2"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Model API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "secret_key": "example string",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete API Key for a Model

/v2/gen-ai/models/api_keys/{api_key_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete an API key for a model, send a DELETE request to /v2/gen-ai/models/api_keys/{api_key_uuid}.

Path Parameters

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key for an agent.

Request: /v2/gen-ai/models/api_keys/{api_key_uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/models/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Model API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "secret_key": "example string",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Regenerate API Key for a Model

/v2/gen-ai/models/api_keys/{api_key_uuid}/regenerate
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To regenerate a model API key, send a PUT request to /v2/gen-ai/models/api_keys/{api_key_uuid}/regenerate.

Path Parameters

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key ID

Request: /v2/gen-ai/models/api_keys/{api_key_uuid}/regenerate
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/models/api_keys/11efcf7e-824d-2808-bf8f-4e013e2ddde4/regenerate"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

Model API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "name": "example name",
    "secret_key": "example string",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Get Oauth2 Dropbox Tokens

/v2/gen-ai/oauth2/dropbox/tokens
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To obtain the refresh token, needed for creation of data sources, send a GET request to /v2/gen-ai/oauth2/dropbox/tokens. Pass the code you obtrained from the oauth flow in the field 'code'

Request Body: application/json

code string optional
Example: example string

The oauth2 code from google

redirect_url string optional
Example: example string

Redirect url

Request: /v2/gen-ai/oauth2/dropbox/tokens
Content type application/json 
{
  "code": "example string",
  "redirect_url": "example string"
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/oauth2/dropbox/tokens?code=<oauth2_code_from_dropbox>"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
refresh_token string optional
Example: example string

The refresh token

token string optional
Example: example string

The access token

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "refresh_token": "example string",
  "token": "example string"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Get Oauth2 URL

/v2/gen-ai/oauth2/url
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To generate an Oauth2-URL for use with your localhost, send a GET request to /v2/gen-ai/oauth2/url. Pass 'http://localhost:3000 as redirect_url

Query Parameters

type string optional
Example: "example string"

Type "google" / "dropbox".

redirect_url string optional
Example: "example string"

The redirect url.

Request: /v2/gen-ai/oauth2/url
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/oauth2/url?type=google&redirect_uri=http://localhost:3000"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
url string optional
Example: example string

The oauth2 url

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "url": "example string"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List OpenAI API Keys

/v2/gen-ai/openai/keys
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all OpenAI API keys, send a GET request to /v2/gen-ai/openai/keys.

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/openai/keys
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/openai/keys"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_infos": [
    {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create OpenAI API Key

/v2/gen-ai/openai/keys
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create an OpenAI API key, send a POST request to /v2/gen-ai/openai/keys.

Request Body: application/json

api_key string optional
Example: "sk-proj--123456789098765432123456789"

OpenAI API key

name string optional
Example: "Production Key"

Name of the key

Request: /v2/gen-ai/openai/keys
Content type application/json 
{
  "api_key": "\"sk-proj--123456789098765432123456789\"",
  "name": "\"Production Key\""
}
curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/openai/keys" \
  -d '{
    "api_key": "sk-proj--12345678901234567890123456789012",
    "name": "test-key"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "models": [],
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Get OpenAI API Key

/v2/gen-ai/openai/keys/{api_key_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To retrieve details of an OpenAI API key, send a GET request to /v2/gen-ai/openai/keys/{api_key_uuid}.

Path Parameters

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key ID

Request: /v2/gen-ai/openai/keys/{api_key_uuid}
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "models": [],
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update OpenAI API Key

/v2/gen-ai/openai/keys/{api_key_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update an OpenAI API key, send a PUT request to /v2/gen-ai/openai/keys/{api_key_uuid}.

Path Parameters

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key ID

Request Body: application/json

api_key string optional
Example: "sk-ant-12345678901234567890123456789012"

OpenAI API key

api_key_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"

API key ID

name string optional
Example: "Production Key"

Name of the key

Request: /v2/gen-ai/openai/keys/{api_key_uuid}
Content type application/json 
{
  "api_key": "\"sk-ant-12345678901234567890123456789012\"",
  "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"Production Key\""
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \
  -d '{
    "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4",
    "name": "test-key2"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "models": [],
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete OpenAI API Key

/v2/gen-ai/openai/keys/{api_key_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete an OpenAI API key, send a DELETE request to /v2/gen-ai/openai/keys/{api_key_uuid}.

Path Parameters

api_key_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

API key ID

Request: /v2/gen-ai/openai/keys/{api_key_uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
api_key_info object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "api_key_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "deleted_at": "2023-01-01T00:00:00Z",
    "models": [],
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List agents by OpenAI key

/v2/gen-ai/openai/keys/{uuid}/agents
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

List Agents by OpenAI Key.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Unique ID of OpenAI key

Query Parameters

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/openai/keys/{uuid}/agents
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/agents"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agents array of object optional
Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agents": [
    {
      "api_key_infos": [],
      "api_keys": [],
      "chatbot_identifiers": [],
      "child_agents": [],
      "conversation_logs_enabled": true,
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "functions": [],
      "guardrails": [],
      "if_case": "example string",
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "max_tokens": 123,
      "name": "example name",
      "parent_agents": [],
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "provide_citations": true,
      "region": "example string",
      "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
      "route_created_at": "2023-01-01T00:00:00Z",
      "route_created_by": "12345",
      "route_name": "example name",
      "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "user_id": "12345",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "version_hash": "example string",
      "vpc_egress_ips": [
        "example string"
      ],
      "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\""
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Datacenter Regions

/v2/gen-ai/regions
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all datacenter regions, send a GET request to /v2/gen-ai/regions.

Query Parameters

serves_inference boolean optional
Example: true

Include datacenters that serve inference.

serves_batch boolean optional
Example: true

Include datacenters that are capable of running batch jobs.

Request: /v2/gen-ai/regions
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/regions"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
regions array of object optional

Region code

Show child properties
inference_url string optional
Example: example string

Url for inference server

region string optional
Example: example string

Region code

serves_batch boolean optional
Example: true

This datacenter is capable of running batch jobs

serves_inference boolean optional
Example: true

This datacenter is capable of serving inference

stream_inference_url string optional
Example: example string

The url for the inference streaming server

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "regions": [
    {
      "inference_url": "example string",
      "region": "example string",
      "serves_batch": true,
      "serves_inference": true,
      "stream_inference_url": "example string"
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create scheduled indexing for knowledge base

/v2/gen-ai/scheduled-indexing
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create scheduled indexing for a knowledge base, send a POST request to /v2/gen-ai/scheduled-indexing.

Request Body: application/json

days array of integer (int32) optional

Days for execution (day is represented same as in a cron expression, e.g. Monday begins with 1 )

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base uuid for which the schedule is created

time string optional
Example: example string

Time of execution (HH:MM) UTC

Request: /v2/gen-ai/scheduled-indexing
Content type application/json 
{
  "days": [
    123
  ],
  "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "time": "example string"
}
curl --location --request POST 'https://api.digitalocean.com/v2/gen-ai/scheduled-indexing' \
--header 'Authorization: Bearer $DIGITALOCEAN_TOKEN"' \
--header 'Content-Type: application/json' \
--data '{
    "knowledge_base_uuid": "knowledge_base_uuid",
    "time": "18:00",
    "days": [
        1,
        2,
        3
    ]
}'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
indexing_info object optional

Metadata for scheduled indexing entries

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Created at timestamp

days array of integer (int32) optional

Days for execution (day is represented same as in a cron expression, e.g. Monday begins with 1 )

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted at timestamp (if soft deleted)

is_active boolean optional
Example: true

Whether the schedule is currently active

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base uuid associated with this schedule

last_ran_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last time the schedule was executed

next_run_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Next scheduled run

time string optional
Example: example string

Scheduled time of execution (HH:MM:SS format)

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Updated at timestamp

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier for the scheduled indexing entry

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "indexing_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "days": [
      123
    ],
    "deleted_at": "2023-01-01T00:00:00Z",
    "is_active": true,
    "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "last_ran_at": "2023-01-01T00:00:00Z",
    "next_run_at": "2023-01-01T00:00:00Z",
    "time": "example string",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Get Scheduled Indexing for Knowledge Base

/v2/gen-ai/scheduled-indexing/knowledge-base/{knowledge_base_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Get Scheduled Indexing for knowledge base using knoweldge base uuid, send a GET request to /v2/gen-ai/scheduled-indexing/knowledge-base/{knowledge_base_uuid}.

Path Parameters

knowledge_base_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

UUID of the scheduled indexing entry

Request: /v2/gen-ai/scheduled-indexing/knowledge-base/{knowledge_base_uuid}
curl --location --request GET 'https://api.digitalocean.com/v2/gen-ai/scheduled-indexing/knowledge-base/{knowledge_base_uuid}' \
--header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' \
--header 'Content-Type: application/json'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
indexing_info object optional

Metadata for scheduled indexing entries

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Created at timestamp

days array of integer (int32) optional

Days for execution (day is represented same as in a cron expression, e.g. Monday begins with 1 )

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted at timestamp (if soft deleted)

is_active boolean optional
Example: true

Whether the schedule is currently active

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base uuid associated with this schedule

last_ran_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last time the schedule was executed

next_run_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Next scheduled run

time string optional
Example: example string

Scheduled time of execution (HH:MM:SS format)

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Updated at timestamp

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier for the scheduled indexing entry

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "indexing_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "days": [
      123
    ],
    "deleted_at": "2023-01-01T00:00:00Z",
    "is_active": true,
    "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "last_ran_at": "2023-01-01T00:00:00Z",
    "next_run_at": "2023-01-01T00:00:00Z",
    "time": "example string",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete Scheduled Indexing

/v2/gen-ai/scheduled-indexing/{uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Delete Scheduled Indexing for knowledge base, send a DELETE request to /v2/gen-ai/scheduled-indexing/{uuid}.

Path Parameters

uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

UUID of the scheduled indexing

Request: /v2/gen-ai/scheduled-indexing/{uuid}
curl --location --request DELETE 'https://api.digitalocean.com/v2/gen-ai/scheduled-indexing/{scheduled_indexing_id}' \
  --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
indexing_info object optional

Metadata for scheduled indexing entries

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Created at timestamp

days array of integer (int32) optional

Days for execution (day is represented same as in a cron expression, e.g. Monday begins with 1 )

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted at timestamp (if soft deleted)

is_active boolean optional
Example: true

Whether the schedule is currently active

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base uuid associated with this schedule

last_ran_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last time the schedule was executed

next_run_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Next scheduled run

time string optional
Example: example string

Scheduled time of execution (HH:MM:SS format)

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Updated at timestamp

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier for the scheduled indexing entry

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "indexing_info": {
    "created_at": "2023-01-01T00:00:00Z",
    "days": [
      123
    ],
    "deleted_at": "2023-01-01T00:00:00Z",
    "is_active": true,
    "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "last_ran_at": "2023-01-01T00:00:00Z",
    "next_run_at": "2023-01-01T00:00:00Z",
    "time": "example string",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Workspaces

/v2/gen-ai/workspaces
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all workspaces, send a GET request to /v2/gen-ai/workspaces.

Request: /v2/gen-ai/workspaces
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/workspaces"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
workspaces array of object optional

Workspaces

Show child properties
agents array of object optional

Agents

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

output_schema object optional
Additional nested properties not shown. Refer to the full API spec for details.
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Additional nested properties not shown. Refer to the full API spec for details.
instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Additional nested properties not shown. Refer to the full API spec for details.
long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time created at.

dataset_name string optional
Example: example name

Name of the dataset.

dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the dataset.

file_size string (uint64) optional
Example: 12345

The size of the dataset uploaded file in bytes.

has_ground_truth boolean optional
Example: true

Does the dataset have a ground truth column?

row_count integer (int64) optional
Example: 123

Number of rows in the dataset.

dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Show child properties
category string (enum) optional
Example: METRIC_CATEGORY_UNSPECIFIED
description string optional
Example: example string
inverted boolean optional
Example: true

If true, the metric is inverted, meaning that a lower value is better.

is_metric_goal boolean optional
Example: true
metric_name string optional
Example: example name
metric_rank integer (int64) optional
Example: 123
metric_type string, one of: METRIC_TYPE_UNSPECIFIED, METRIC_TYPE_GENERAL_QUALITY, METRIC_TYPE_RAG_AND_TOOL optional
Example: METRIC_TYPE_UNSPECIFIED
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
range_max number (float) optional
Example: 123

The maximum value for the metric.

range_min number (float) optional
Example: 123

The minimum value for the metric.

name string optional
Example: example name
star_metric object optional
Show child properties
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
name string optional
Example: example name
success_threshold number (float) optional
Example: 123

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

success_threshold_pct integer (int32) optional
Example: 123

The success threshold for the star metric. This is a percentage value between 0 and 100.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "workspaces": [
    {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create a Workspace

/v2/gen-ai/workspaces
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To create a new workspace, send a POST request to /v2/gen-ai/workspaces. The response body contains a JSON object with the newly created workspace object.

Request Body: application/json

agent_uuids array of string optional
Example: ["example string"]

Ids of the agents(s) to attach to the workspace

description string optional
Example: example string

Description of the workspace

name string optional
Example: example name

Name of the workspace

Request: /v2/gen-ai/workspaces
Content type application/json 
{
  "agent_uuids": [
    "example string"
  ],
  "description": "example string",
  "name": "example name"
}
curl -X POST \
    -H "Content-Type: application/json"  \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    "https://api.digitalocean.com/v2/gen-ai/workspaces" \
    -d '{
      "name": "api-create",
      "description": "This is a test workspace created via the API",
      "agent_uuids": [
        "9758a232-b351-11ef-bf8f-4e013e2ddde4"
      ]
    }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
workspace object optional
Show child properties
agents array of object optional

Agents

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

output_schema object optional
Additional nested properties not shown. Refer to the full API spec for details.
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Additional nested properties not shown. Refer to the full API spec for details.
instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Additional nested properties not shown. Refer to the full API spec for details.
long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time created at.

dataset_name string optional
Example: example name

Name of the dataset.

dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the dataset.

file_size string (uint64) optional
Example: 12345

The size of the dataset uploaded file in bytes.

has_ground_truth boolean optional
Example: true

Does the dataset have a ground truth column?

row_count integer (int64) optional
Example: 123

Number of rows in the dataset.

dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Show child properties
category string (enum) optional
Example: METRIC_CATEGORY_UNSPECIFIED
description string optional
Example: example string
inverted boolean optional
Example: true

If true, the metric is inverted, meaning that a lower value is better.

is_metric_goal boolean optional
Example: true
metric_name string optional
Example: example name
metric_rank integer (int64) optional
Example: 123
metric_type string, one of: METRIC_TYPE_UNSPECIFIED, METRIC_TYPE_GENERAL_QUALITY, METRIC_TYPE_RAG_AND_TOOL optional
Example: METRIC_TYPE_UNSPECIFIED
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
range_max number (float) optional
Example: 123

The maximum value for the metric.

range_min number (float) optional
Example: 123

The minimum value for the metric.

name string optional
Example: example name
star_metric object optional
Show child properties
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
name string optional
Example: example name
success_threshold number (float) optional
Example: 123

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

success_threshold_pct integer (int32) optional
Example: 123

The success threshold for the star metric. This is a percentage value between 0 and 100.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "workspace": {
    "agents": [],
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "created_by_email": "[email protected]",
    "deleted_at": "2023-01-01T00:00:00Z",
    "description": "example string",
    "evaluation_test_cases": [],
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an Existing Workspace

/v2/gen-ai/workspaces/{workspace_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To retrieve details of a workspace, GET request to /v2/gen-ai/workspaces/{workspace_uuid}. The response body is a JSON object containing the workspace.

Path Parameters

workspace_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Workspace UUID.

Request: /v2/gen-ai/workspaces/{workspace_uuid}
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/workspaces/c441bf77-81d6-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
workspace object optional
Show child properties
agents array of object optional

Agents

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

output_schema object optional
Additional nested properties not shown. Refer to the full API spec for details.
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Additional nested properties not shown. Refer to the full API spec for details.
instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Additional nested properties not shown. Refer to the full API spec for details.
long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time created at.

dataset_name string optional
Example: example name

Name of the dataset.

dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the dataset.

file_size string (uint64) optional
Example: 12345

The size of the dataset uploaded file in bytes.

has_ground_truth boolean optional
Example: true

Does the dataset have a ground truth column?

row_count integer (int64) optional
Example: 123

Number of rows in the dataset.

dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Show child properties
category string (enum) optional
Example: METRIC_CATEGORY_UNSPECIFIED
description string optional
Example: example string
inverted boolean optional
Example: true

If true, the metric is inverted, meaning that a lower value is better.

is_metric_goal boolean optional
Example: true
metric_name string optional
Example: example name
metric_rank integer (int64) optional
Example: 123
metric_type string, one of: METRIC_TYPE_UNSPECIFIED, METRIC_TYPE_GENERAL_QUALITY, METRIC_TYPE_RAG_AND_TOOL optional
Example: METRIC_TYPE_UNSPECIFIED
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
range_max number (float) optional
Example: 123

The maximum value for the metric.

range_min number (float) optional
Example: 123

The minimum value for the metric.

name string optional
Example: example name
star_metric object optional
Show child properties
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
name string optional
Example: example name
success_threshold number (float) optional
Example: 123

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

success_threshold_pct integer (int32) optional
Example: 123

The success threshold for the star metric. This is a percentage value between 0 and 100.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "workspace": {
    "agents": [],
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "created_by_email": "[email protected]",
    "deleted_at": "2023-01-01T00:00:00Z",
    "description": "example string",
    "evaluation_test_cases": [],
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update a Workspace

/v2/gen-ai/workspaces/{workspace_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To update a workspace, send a PUT request to /v2/gen-ai/workspaces/{workspace_uuid}. The response body is a JSON object containing the workspace.

Path Parameters

workspace_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Workspace UUID.

Request Body: application/json

description string optional
Example: example string

The new description of the workspace

name string optional
Example: example name

The new name of the workspace

workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Workspace UUID.

Request: /v2/gen-ai/workspaces/{workspace_uuid}
Content type application/json 
{
  "description": "example string",
  "name": "example name",
  "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/workspaces/1b418231-b7d6-11ef-bf8f-4e013e2ddde4" \
  -d '{
    "workspace_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "name": "rename-agent-api",
    "description": "workspace description"
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
workspace object optional
Show child properties
agents array of object optional

Agents

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

output_schema object optional
Additional nested properties not shown. Refer to the full API spec for details.
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Additional nested properties not shown. Refer to the full API spec for details.
instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Additional nested properties not shown. Refer to the full API spec for details.
long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time created at.

dataset_name string optional
Example: example name

Name of the dataset.

dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the dataset.

file_size string (uint64) optional
Example: 12345

The size of the dataset uploaded file in bytes.

has_ground_truth boolean optional
Example: true

Does the dataset have a ground truth column?

row_count integer (int64) optional
Example: 123

Number of rows in the dataset.

dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Show child properties
category string (enum) optional
Example: METRIC_CATEGORY_UNSPECIFIED
description string optional
Example: example string
inverted boolean optional
Example: true

If true, the metric is inverted, meaning that a lower value is better.

is_metric_goal boolean optional
Example: true
metric_name string optional
Example: example name
metric_rank integer (int64) optional
Example: 123
metric_type string, one of: METRIC_TYPE_UNSPECIFIED, METRIC_TYPE_GENERAL_QUALITY, METRIC_TYPE_RAG_AND_TOOL optional
Example: METRIC_TYPE_UNSPECIFIED
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
range_max number (float) optional
Example: 123

The maximum value for the metric.

range_min number (float) optional
Example: 123

The minimum value for the metric.

name string optional
Example: example name
star_metric object optional
Show child properties
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
name string optional
Example: example name
success_threshold number (float) optional
Example: 123

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

success_threshold_pct integer (int32) optional
Example: 123

The success threshold for the star metric. This is a percentage value between 0 and 100.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "workspace": {
    "agents": [],
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "created_by_email": "[email protected]",
    "deleted_at": "2023-01-01T00:00:00Z",
    "description": "example string",
    "evaluation_test_cases": [],
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a Workspace

/v2/gen-ai/workspaces/{workspace_uuid}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To delete a workspace, send a DELETE request to /v2/gen-ai/workspace/{workspace_uuid}.

Path Parameters

workspace_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Workspace UUID.

Request: /v2/gen-ai/workspaces/{workspace_uuid}
curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/workspaces/5581a586-a745-11ef-bf8f-4e013e2ddde4"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Workspace

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List agents by Workspace

/v2/gen-ai/workspaces/{workspace_uuid}/agents
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all agents by a Workspace, send a GET request to /v2/gen-ai/workspaces/{workspace_uuid}/agents.

Path Parameters

workspace_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Workspace UUID.

Query Parameters

only_deployed boolean optional
Example: true

Only list agents that are deployed.

page integer optional
Example: 1

Page number.

per_page integer optional
Example: 1

Items per page.

Request: /v2/gen-ai/workspaces/{workspace_uuid}/agents
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/workspaces/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/agents"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
agents array of object optional
Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
name string optional
Example: example name

Name

output_schema object optional
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Show child properties
completed_datasources integer (int64) optional
Example: 123

Number of datasources indexed completed

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

data_source_jobs array of object optional

Details on Data Sources included in the Indexing Job

Additional nested properties not shown. Refer to the full API spec for details.
data_source_uuids array of string optional
Example: ["example string"]
finished_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
is_report_available boolean optional
Example: true

Boolean value to determine if the indexing job details are available

knowledge_base_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Knowledge base id

phase string (enum) optional
Example: BATCH_JOB_PHASE_UNKNOWN
started_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
status string (enum) optional
Example: INDEX_JOB_STATUS_UNKNOWN
tokens integer (int64) optional
Example: 123

Number of tokens [This field is deprecated]

total_datasources integer (int64) optional
Example: 123

Number of datasources being indexed

total_tokens string (uint64) optional
Example: 12345

Total Tokens Consumed By the Indexing Job

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Show child properties
description string optional
Example: example string
name string optional
Example: example name
url string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Show child properties
major integer (int64) optional
Example: 123

Major version number

minor integer (int64) optional
Example: 123

Minor version number

patch integer (int64) optional
Example: 123

Patch version number

model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Show child properties
priority integer (int32) optional
Example: 123

Priority of the guardrail

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid of the guardrail

instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
Show child properties
agents array of object optional

Agents

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Additional nested properties not shown. Refer to the full API spec for details.
dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
star_metric object optional
Additional nested properties not shown. Refer to the full API spec for details.
test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

links object optional

Links to other pages

Show child properties
pages object optional

Information about how to reach other pages

Show child properties
first string optional
Example: example string

First page

last string optional
Example: example string

Last page

next string optional
Example: example string

Next page

previous string optional
Example: example string

Previous page

meta object optional

Meta information about the data set

Show child properties
page integer (int64) optional
Example: 123

The current page

pages integer (int64) optional
Example: 123

Total number of pages

total integer (int64) optional
Example: 123

Total amount of items over all pages

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "agents": [
    {
      "api_key_infos": [],
      "api_keys": [],
      "chatbot_identifiers": [],
      "child_agents": [],
      "conversation_logs_enabled": true,
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "functions": [],
      "guardrails": [],
      "if_case": "example string",
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "max_tokens": 123,
      "name": "example name",
      "parent_agents": [],
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "provide_citations": true,
      "region": "example string",
      "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
      "route_created_at": "2023-01-01T00:00:00Z",
      "route_created_by": "12345",
      "route_name": "example name",
      "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "user_id": "12345",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "version_hash": "example string",
      "vpc_egress_ips": [
        "example string"
      ],
      "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\""
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Move Agents to a Workspace

/v2/gen-ai/workspaces/{workspace_uuid}/agents
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To move all listed agents a given workspace, send a PUT request to /v2/gen-ai/workspaces/{workspace_uuid}/agents.

Path Parameters

workspace_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Workspace uuid to move agents to

Request Body: application/json

agent_uuids array of string optional
Example: ["example string"]

Agent uuids

workspace_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Workspace uuid to move agents to

Request: /v2/gen-ai/workspaces/{workspace_uuid}/agents
Content type application/json 
{
  "agent_uuids": [
    "example string"
  ],
  "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
curl -X PUT \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/workspaces/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/agents" \
  -d '{
    "workspace_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4",
    "agent_uuids": ["95ea6652-75ed-11ef-bf8f-4e013e2ddde4", "37455431-84bd-4fa2-94cf-e8486f8f8c5e"]
  }'

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
workspace object optional
Show child properties
agents array of object optional

Agents

Show child properties
anthropic_api_key object optional

Anthropic API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_key_infos array of object optional

Api key infos

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

Created by

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

name string optional
Example: example name

Name

secret_key string optional
Example: example string
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

api_keys array of object optional

Api keys

Show child properties
api_key string optional
Example: example string

Api key

chatbot object optional

A Chatbot

Show child properties
allowed_domains array of string optional
Example: ["example string"]
button_background_color string optional
Example: example string
logo string optional
Example: example string
name string optional
Example: example name

Name of chatbot

primary_color string optional
Example: example string
secondary_color string optional
Example: example string
starting_message string optional
Example: example string
chatbot_identifiers array of object optional

Chatbot identifiers

Show child properties
agent_chatbot_identifier string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Agent chatbot identifier

child_agents array of object optional

Child agents

conversation_logs_enabled boolean optional
Example: true

Whether conversation logs are enabled for the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

deployment object optional

Description of deployment

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

name string optional
Example: example name

Name

status string (enum) optional
Example: STATUS_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your deployed agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

visibility string, one of: VISIBILITY_UNKNOWN, VISIBILITY_DISABLED, VISIBILITY_PLAYGROUND, VISIBILITY_PUBLIC, VISIBILITY_PRIVATE optional
Example: VISIBILITY_UNKNOWN
  • VISIBILITY_UNKNOWN: The status of the deployment is unknown
  • VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests
  • VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state
  • VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet
  • VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys
description string optional
Example: example string

Description of agent

functions array of object optional
Show child properties
api_key string optional
Example: example string

Api key

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

created_by string (uint64) optional
Example: 12345

Created by user id from DO

description string optional
Example: example string

Agent description

faas_name string optional
Example: example name
faas_namespace string optional
Example: example name
input_schema object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

output_schema object optional
Additional nested properties not shown. Refer to the full API spec for details.
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Download your agent here

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

guardrails array of object optional

The guardrails the agent is attached to

Show child properties
agent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
default_response string optional
Example: example string
description string optional
Example: example string
guardrail_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_attached boolean optional
Example: true
is_default boolean optional
Example: true
metadata object optional
Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name
priority integer (int32) optional
Example: 123
type string, one of: GUARDRAIL_TYPE_UNKNOWN, GUARDRAIL_TYPE_JAILBREAK, GUARDRAIL_TYPE_SENSITIVE_DATA, GUARDRAIL_TYPE_CONTENT_MODERATION optional
Example: GUARDRAIL_TYPE_UNKNOWN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
if_case string optional
Example: example string
instruction string optional
Example: example string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k integer (int64) optional
Example: 123
knowledge_bases array of object optional

Knowledge bases

Show child properties
added_to_agent_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time when the knowledge base was added to the agent

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

database_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
embedding_model_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
is_public boolean optional
Example: true

Whether the knowledge base is public or not

last_indexing_job object optional

IndexingJob description

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of knowledge base

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
region string optional
Example: example string

Region code

tags array of string optional
Example: ["example string"]

Tags to organize related resources

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

user_id string (int64) optional
Example: 12345

Id of user that created the knowledge base

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id for knowledge base

logging_config object optional
Show child properties
galileo_project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Galileo project identifier

galileo_project_name string optional
Example: example name

Name of the Galileo project

insights_enabled boolean optional
Example: true

Whether insights are enabled

insights_enabled_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Timestamp when insights were enabled

log_stream_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the log stream

log_stream_name string optional
Example: example name

Name of the log stream

max_tokens integer (int64) optional
Example: 123
model object optional

Description of a Model

Show child properties
agreement object optional

Agreement Description

Additional nested properties not shown. Refer to the full API spec for details.
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date / time

inference_name string optional
Example: example name

Internally used name

inference_version string optional
Example: example string

Internally used version

is_foundational boolean optional
Example: true

True if it is a foundational model provided by do

kb_default_chunk_size integer (int64) optional
Example: 123

Default chunking size limit to show in UI

kb_max_chunk_size integer (int64) optional
Example: 123

Maximum chunk size limit of model

kb_min_chunk_size integer (int64) optional
Example: 123

Minimum chunking size token limits if model supports KNOWLEDGEBASE usecase

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the model

parent_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id of the model, this model is based on

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

upload_complete boolean optional
Example: true

Model has been fully uploaded

url string optional
Example: example string

Download url

usecases array of string (enum) optional
Example: ["MODEL_USECASE_AGENT","MODEL_USECASE_GUARDRAIL"]

Usecases of the model

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

version object optional

Version Information about a Model

Additional nested properties not shown. Refer to the full API spec for details.
model_provider_key object optional
Show child properties
api_key_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

API key ID

created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the key

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional
Example: MODEL_PROVIDER_DIGITALOCEAN
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

name string optional
Example: example name

Agent name

openai_api_key object optional

OpenAI API Key Info

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key creation date

created_by string (uint64) optional
Example: 12345

Created by user id from DO

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key deleted date

models array of object optional

Models supported by the openAI api key

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Key last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Uuid

parent_agents array of object optional

Parent agents

project_id string optional
Example: 123e4567-e89b-12d3-a456-426614174000
provide_citations boolean optional
Example: true

Whether the agent should provide in-response citations

region string optional
Example: example string

Region code

retrieval_method string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional
Example: RETRIEVAL_METHOD_UNKNOWN
  • RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown
  • RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite
  • RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back
  • RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries
  • RETRIEVAL_METHOD_NONE: The retrieval method is none
route_created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation of route date / time

route_created_by string (uint64) optional
Example: 12345
route_name string optional
Example: example name

Route name

route_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
tags array of string optional
Example: ["example string"]

Agent tag to organize related resources

temperature number (float) optional
Example: 123
template object optional

Represents an AgentTemplate entity

Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's creation date

description string optional
Example: example string

Deprecated - Use summary instead

guardrails array of object optional

List of guardrails associated with the agent template

Additional nested properties not shown. Refer to the full API spec for details.
instruction string optional
Example: example string

Instructions for the agent template

k integer (int64) optional
Example: 123

The 'k' value for the agent template

knowledge_bases array of object optional

List of knowledge bases associated with the agent template

Additional nested properties not shown. Refer to the full API spec for details.
long_description string optional

The long description of the agent template

max_tokens integer (int64) optional
Example: 123

The max_tokens setting for the agent template

model object optional

Description of a Model

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: example name

Name of the agent template

short_description string optional

The short description of the agent template

summary string optional
Example: example string

The summary of the agent template

tags array of string optional
Example: ["example string"]

List of tags associated with the agent template

temperature number (float) optional
Example: 123

The temperature setting for the agent template

template_type string, one of: AGENT_TEMPLATE_TYPE_STANDARD, AGENT_TEMPLATE_TYPE_ONE_CLICK optional
Example: AGENT_TEMPLATE_TYPE_STANDARD
  • AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template
  • AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template
top_p number (float) optional
Example: 123

The top_p setting for the agent template

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

The agent template's last updated date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

top_p number (float) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Last modified

url string optional
Example: example string

Access your agent under this url

user_id string (uint64) optional
Example: 12345

Id of user that created the agent

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique agent id

version_hash string optional
Example: example string

The latest version of the agent

vpc_egress_ips array of string optional
Example: ["example string"]

VPC Egress IPs

vpc_uuid string optional
Example: "12345678-1234-1234-1234-123456789012"
workspace object optional
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Creation date

created_by string (uint64) optional
Example: 12345

The id of user who created this workspace

created_by_email string optional
Example: [email protected]

The email of the user who created this workspace

deleted_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Deleted date

description string optional
Example: example string

Description of the workspace

evaluation_test_cases array of object optional

Evaluations

Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time created at.

dataset_name string optional
Example: example name

Name of the dataset.

dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the dataset.

file_size string (uint64) optional
Example: 12345

The size of the dataset uploaded file in bytes.

has_ground_truth boolean optional
Example: true

Does the dataset have a ground truth column?

row_count integer (int64) optional
Example: 123

Number of rows in the dataset.

dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Show child properties
category string (enum) optional
Example: METRIC_CATEGORY_UNSPECIFIED
description string optional
Example: example string
inverted boolean optional
Example: true

If true, the metric is inverted, meaning that a lower value is better.

is_metric_goal boolean optional
Example: true
metric_name string optional
Example: example name
metric_rank integer (int64) optional
Example: 123
metric_type string, one of: METRIC_TYPE_UNSPECIFIED, METRIC_TYPE_GENERAL_QUALITY, METRIC_TYPE_RAG_AND_TOOL optional
Example: METRIC_TYPE_UNSPECIFIED
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
range_max number (float) optional
Example: 123

The maximum value for the metric.

range_min number (float) optional
Example: 123

The minimum value for the metric.

name string optional
Example: example name
star_metric object optional
Show child properties
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
name string optional
Example: example name
success_threshold number (float) optional
Example: 123

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

success_threshold_pct integer (int32) optional
Example: 123

The success threshold for the star metric. This is a percentage value between 0 and 100.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
name string optional
Example: example name

Name of the workspace

updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Update date

uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

Unique id

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "workspace": {
    "agents": [],
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "12345",
    "created_by_email": "[email protected]",
    "deleted_at": "2023-01-01T00:00:00Z",
    "description": "example string",
    "evaluation_test_cases": [],
    "name": "example name",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Evaluation Test Cases by Workspace

/v2/gen-ai/workspaces/{workspace_uuid}/evaluation_test_cases
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: genai:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To list all evaluation test cases by a workspace, send a GET request to /v2/gen-ai/workspaces/{workspace_uuid}/evaluation_test_cases.

Path Parameters

workspace_uuid string required
Example: "123e4567-e89b-12d3-a456-426614174000"

Workspace UUID.

Request: /v2/gen-ai/workspaces/{workspace_uuid}/evaluation_test_cases
curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/workspaces/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/evaluation_test_cases"

Responses

200

A successful response.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
evaluation_test_cases array of object optional
Show child properties
archived_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
created_by_user_email string optional
Example: [email protected]
created_by_user_id string (uint64) optional
Example: 12345
dataset object optional
Show child properties
created_at string (date-time) optional
Example: 2023-01-01T00:00:00Z

Time created at.

dataset_name string optional
Example: example name

Name of the dataset.

dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the dataset.

file_size string (uint64) optional
Example: 12345

The size of the dataset uploaded file in bytes.

has_ground_truth boolean optional
Example: true

Does the dataset have a ground truth column?

row_count integer (int64) optional
Example: 123

Number of rows in the dataset.

dataset_name string optional
Example: example name
dataset_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
description string optional
Example: example string
latest_version_number_of_runs integer (int32) optional
Example: 123
metrics array of object optional
Show child properties
category string (enum) optional
Example: METRIC_CATEGORY_UNSPECIFIED
description string optional
Example: example string
inverted boolean optional
Example: true

If true, the metric is inverted, meaning that a lower value is better.

is_metric_goal boolean optional
Example: true
metric_name string optional
Example: example name
metric_rank integer (int64) optional
Example: 123
metric_type string, one of: METRIC_TYPE_UNSPECIFIED, METRIC_TYPE_GENERAL_QUALITY, METRIC_TYPE_RAG_AND_TOOL optional
Example: METRIC_TYPE_UNSPECIFIED
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
metric_value_type string, one of: METRIC_VALUE_TYPE_UNSPECIFIED, METRIC_VALUE_TYPE_NUMBER, METRIC_VALUE_TYPE_STRING, METRIC_VALUE_TYPE_PERCENTAGE optional
Example: METRIC_VALUE_TYPE_UNSPECIFIED
range_max number (float) optional
Example: 123

The maximum value for the metric.

range_min number (float) optional
Example: 123

The minimum value for the metric.

name string optional
Example: example name
star_metric object optional
Show child properties
metric_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
name string optional
Example: example name
success_threshold number (float) optional
Example: 123

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

success_threshold_pct integer (int32) optional
Example: 123

The success threshold for the star metric. This is a percentage value between 0 and 100.

test_case_uuid string optional
Example: 123e4567-e89b-12d3-a456-426614174000
total_runs integer (int32) optional
Example: 123
updated_at string (date-time) optional
Example: 2023-01-01T00:00:00Z
updated_by_user_email string optional
Example: [email protected]
updated_by_user_id string (uint64) optional
Example: 12345
version integer (int64) optional
Example: 123
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "evaluation_test_cases": [
    {
      "archived_at": "2023-01-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by_user_email": "[email protected]",
      "created_by_user_id": "12345",
      "dataset_name": "example name",
      "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "description": "example string",
      "latest_version_number_of_runs": 123,
      "metrics": [],
      "name": "example name",
      "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "total_runs": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "updated_by_user_email": "[email protected]",
      "updated_by_user_id": "12345",
      "version": 123
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

We can't find any results for your search.

Try using different keywords or simplifying your search terms.