Give Feedback

GradientAI Platform

Generated on 25 May 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 GET List Custom Models POST Import Custom Model GET Get Custom Model DELETE Delete Custom Model PATCH Update Custom Model Metadata POST Create Evaluation Dataset POST Create Presigned URLs for Evaluation Dataset File Upload GET Get Download URL for Evaluation Dataset 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 POST Create Presigned URLs for Model Evaluation Dataset File Upload GET List Model Evaluation Metrics GET List Model Evaluation Presets GET Retrieve Model Evaluation Preset GET List Model Evaluation Runs POST Create Model Evaluation Run GET Retrieve Model Evaluation Run DELETE Delete Model Evaluation Run GET Get Download URL for Model Evaluation Run Results 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 GET List Model Catalog GET Get Model Catalog Card GET List Model Routers POST Create a Model Router GET List Model Router Presets GET List Model Router Task Presets GET Retrieve an Existing Model Router PUT Update a Model Router DELETE Delete a Model Router 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

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.

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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: 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

reasoning_effort string optional

Example: "low"

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 1000

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

previous string optional

Example: example string

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
      "mcp_servers": [],
      "name": "My Agent",
      "project_id": "12345678-1234-1234-1234-123456789012",
      "provide_citations": true,
      "reasoning_effort": "\"low\"",
      "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,
      "thinking_token_budget": 1000,
      "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers to attach to the agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

model_provider_key_uuid string optional

Example: "12345678-1234-1234-1234-123456789012"

model_router_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

reasoning_effort string optional

Example: "low"

region string optional

Example: "tor1"

The DigitalOcean region to deploy your agent in

router_preset_slug string optional

Example: "general"

tags array of string optional

Example: ["example string"]

Agent tag to organize related resources

thinking_token_budget integer (int64) optional

Example: 123

workspace_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the workspace

Request: `/v2/gen-ai/agents`

Payload

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"
  ],
  "mcp_servers": [
    {
      "allowed_tools": [
        "example string"
      ],
      "authorization": "example string",
      "server_label": "example string",
      "server_url": "example string"
    }
  ],
  "model_provider_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "model_router_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\"",
  "reasoning_effort": "\"low\"",
  "region": "\"tor1\"",
  "router_preset_slug": "\"general\"",
  "tags": [
    "example string"
  ],
  "thinking_token_budget": 123,
  "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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`

Payload

Content type application/json

{
  "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "Production Key"
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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}`

Payload

Content type application/json

{
  "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"Production Key\""
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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`

Payload

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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}`

Payload

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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`

Payload

Content type application/json

{
  "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "guardrails": [
    {
      "guardrail_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "priority": 123
    }
  ]
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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}`

Payload

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "child_agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "parent_agent_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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}`

Payload

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "child_agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "parent_agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "rollback": true,
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "child_agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "parent_agent_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

clear_mcp_servers boolean optional

Example: true

When true, removes all MCP servers from the agent. Use this instead of sending an empty mcp_servers array.

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.

mcp_servers array of object optional

MCP (Model Context Protocol) servers to attach to the agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

model_provider_key_uuid string optional

Example: "12345678-1234-1234-1234-123456789012"

Optional Model Provider uuid for use with provider models

model_router_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 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

reasoning_effort string optional

Example: "low"

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

router_preset_slug string optional

Example: "general"

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.

thinking_token_budget integer (int64) optional

Example: 123

top_p number (float) optional

Example: 0.9

uuid string optional

Example: "12345678-1234-1234-1234-123456789012"

Unique agent id

Request: `/v2/gen-ai/agents/{uuid}`

Payload

Content type application/json

{
  "agent_log_insights_enabled": true,
  "allowed_domains": [
    "example string"
  ],
  "anthropic_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "clear_mcp_servers": true,
  "conversation_logs_enabled": true,
  "description": "\"My Agent Description\"",
  "instruction": "\"You are an agent who thinks deeply about the world\"",
  "k": 5,
  "max_tokens": 100,
  "mcp_servers": [
    {
      "allowed_tools": [
        "example string"
      ],
      "authorization": "example string",
      "server_label": "example string",
      "server_url": "example string"
    }
  ],
  "model_provider_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "model_router_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,
  "reasoning_effort": "\"low\"",
  "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
  "router_preset_slug": "\"general\"",
  "tags": [
    "example string"
  ],
  "temperature": 0.7,
  "thinking_token_budget": 123,
  "top_p": 0.9,
  "uuid": "\"12345678-1234-1234-1234-123456789012\""
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
      "mcp_servers": [],
      "name": "example name",
      "parent_agents": [],
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "provide_citations": true,
      "reasoning_effort": "example string",
      "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,
      "thinking_token_budget": 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\""
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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`

Payload

Content type application/json

{
  "uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "visibility": "VISIBILITY_UNKNOWN"
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "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,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "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,
    "reasoning_effort": "example string",
    "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"
    },
    "thinking_token_budget": 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\"",
    "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"
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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`

Payload

Content type application/json

{
  "uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "version_hash": "c3658d8b5c05494cd03ce042926ef08157889ed54b1b74b5ee0b3d66dcee4b73"
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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`

Payload

Content type application/json

{
  "api_key": "\"sk-ant-12345678901234567890123456789012\"",
  "name": "\"Production Key\""
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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}`

Payload

Content type application/json

{
  "api_key": "\"sk-ant-12345678901234567890123456789012\"",
  "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"Production Key\""
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

previous string optional

Example: example string

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
      "mcp_servers": [],
      "name": "example name",
      "parent_agents": [],
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "provide_citations": true,
      "reasoning_effort": "example string",
      "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,
      "thinking_token_budget": 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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET List Custom Models

/v2/gen-ai/custom_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.

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.

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

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`

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 custom models, send a GET request to /v2/gen-ai/custom_models.

Query Parameters

page integer optional

Example: 1

Page number for pagination.

per_page integer optional

Example: 1

Number of items per page.

status string, one of: STATUS_UNSPECIFIED, STATUS_IMPORTING, STATUS_READY, STATUS_FAILED, STATUS_DELETED optional

Example: STATUS_UNSPECIFIED

Filter by model status.

Default: STATUS_UNSPECIFIED

Request: `/v2/gen-ai/custom_models`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/custom_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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

max_threshold integer (int64) optional

Example: 123

Maximum number of custom models allowed for this team's tier

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

List of custom models

Show child properties

active_deployments array of object optional

List of active deployments using this model

Show child properties

created_at string optional

Example: example string

RFC 3339 timestamp indicating when the dedicated inference deployment was created

endpoints object optional

Endpoint URLs for a dedicated inference deployment associated with a custom model.

Show child properties

private_endpoint_fqdn string optional

Example: example string

Private FQDN for the deployment

public_endpoint_fqdn string optional

Example: example string

Public FQDN for the deployment

id string optional

Example: example string

Unique identifier (UUID) of the dedicated inference deployment

name string optional

Example: example name

Human-readable name of the dedicated inference deployment

region_slug string optional

Example: example string

Slug of the region where the dedicated inference deployment is running (e.g. "atl1")

state string optional

Example: example string

Current lifecycle state of the dedicated inference deployment (e.g. "ACTIVE", "PROVISIONING")

updated_at string optional

Example: 2023-01-01

RFC 3339 timestamp indicating when the dedicated inference deployment was last updated

architecture string optional

Example: example string

Model architecture type (free-form string from config.json)

config_json object optional

Raw config.json contents from the model repository

context_length integer (int64) optional

Example: 123

Maximum context length supported by the model

cost_estimate_per_month integer (int64) optional

Example: 123

Estimated monthly cost in dollars for hosting

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the model was created

description string optional

Example: example string

Description of the custom model

file_count integer (int64) optional

Example: 123

Number of files in the model

input_modalities array of string optional

Example: ["example string"]

Input modalities supported (e.g., text, image)

license string optional

Example: example string

License under which the model is distributed

name string optional

Example: example name

Name of the custom model

output_modalities array of string optional

Example: ["example string"]

Output modalities supported (e.g., text, image)

parameters string (uint64) optional

Example: 12345

Number of parameters in the model

source_ref object optional

Reference to the original source of the model

Show child properties

access_type string, one of: ACCESS_TYPE_UNSPECIFIED, ACCESS_TYPE_PUBLIC, ACCESS_TYPE_PRIVATE, ACCESS_TYPE_GATED optional

Example: ACCESS_TYPE_UNSPECIFIED

Access level required for the model repository

bucket string optional

Example: example string

Spaces bucket name

commit_sha string optional

Example: example string

Git commit SHA of the model version

hf_token string optional

Example: example string

User-provided HuggingFace token for gated/private models (not persisted in source_ref)

prefix string optional

Example: example string

Object prefix path in the bucket

region string optional

Example: example string

Spaces bucket region

repo_id string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Huggingface repository identifier

source_type string, one of: SOURCE_TYPE_UNSPECIFIED, SOURCE_TYPE_HUGGINGFACE, SOURCE_TYPE_SPACES_BUCKET, SOURCE_TYPE_SDK_UPLOAD, SOURCE_TYPE_FINE_TUNING optional

Example: SOURCE_TYPE_UNSPECIFIED

Source from which the model was imported

status string, one of: STATUS_UNSPECIFIED, STATUS_IMPORTING, STATUS_READY, STATUS_FAILED, STATUS_DELETED optional

Example: STATUS_UNSPECIFIED

Import and deployment status of the custom model

storage_region string optional

Example: example string

Region of the Spaces bucket where model files are stored

tags object optional

User-defined tags for organizing models

Show child properties

tags array of string optional

Example: ["example string"]

List of tag strings

team_id string (uint64) optional

Example: 12345

Team that owns the model

total_size_bytes string (uint64) optional

Example: 12345

Total size of model files in bytes

updated_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the model was last updated

uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier for the custom model

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "max_threshold": 123,
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  },
  "models": [
    {
      "active_deployments": [],
      "architecture": "example string",
      "context_length": 123,
      "cost_estimate_per_month": 123,
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "file_count": 123,
      "input_modalities": [
        "example string"
      ],
      "license": "example string",
      "name": "example name",
      "output_modalities": [
        "example string"
      ],
      "parameters": "12345",
      "source_type": "SOURCE_TYPE_UNSPECIFIED",
      "status": "STATUS_UNSPECIFIED",
      "storage_region": "example string",
      "team_id": "12345",
      "total_size_bytes": "12345",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Import Custom Model

/v2/gen-ai/custom_models/import

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.

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.

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

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`

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 import a custom model, send a POST request to /v2/gen-ai/custom_models/import.

Request Body: `application/json`

accept_terms_and_conditions boolean optional

Example: true

Whether the caller accepts the terms and conditions for importing this model

description string optional

Example: Production model for customer support

Description of the model

name string optional

Example: my-mistral-7b

Name for the imported model

preferred_gpu_region string optional

Example: nyc3

Preferred GPU region for deployment

source_ref object optional

Reference to the original source of the model

Show child properties

access_type string, one of: ACCESS_TYPE_UNSPECIFIED, ACCESS_TYPE_PUBLIC, ACCESS_TYPE_PRIVATE, ACCESS_TYPE_GATED optional

Example: ACCESS_TYPE_UNSPECIFIED

Access level required for the model repository

bucket string optional

Example: example string

Spaces bucket name

commit_sha string optional

Example: example string

Git commit SHA of the model version

hf_token string optional

Example: example string

User-provided HuggingFace token for gated/private models (not persisted in source_ref)

prefix string optional

Example: example string

Object prefix path in the bucket

region string optional

Example: example string

Spaces bucket region

repo_id string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Huggingface repository identifier

source_type string, one of: SOURCE_TYPE_UNSPECIFIED, SOURCE_TYPE_HUGGINGFACE, SOURCE_TYPE_SPACES_BUCKET, SOURCE_TYPE_SDK_UPLOAD, SOURCE_TYPE_FINE_TUNING optional

Example: SOURCE_TYPE_UNSPECIFIED

Source from which the model was imported

tags object optional

User-defined tags for organizing models

Show child properties

tags array of string optional

Example: ["example string"]

List of tag strings

Request: `/v2/gen-ai/custom_models/import`

Payload

Content type application/json

{
  "accept_terms_and_conditions": true,
  "description": "Production model for customer support",
  "name": "my-mistral-7b",
  "preferred_gpu_region": "nyc3",
  "source_ref": {
    "access_type": "ACCESS_TYPE_UNSPECIFIED",
    "bucket": "example string",
    "commit_sha": "example string",
    "hf_token": "example string",
    "prefix": "example string",
    "region": "example string",
    "repo_id": "123e4567-e89b-12d3-a456-426614174000"
  },
  "source_type": "SOURCE_TYPE_UNSPECIFIED",
  "tags": {
    "tags": [
      "example string"
    ]
  }
}

cURL

curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/custom_models/import" \
  -d '{
    "name": "mymodelssss",
    "source_type": "SOURCE_TYPE_HUGGINGFACE",
    "source_ref": {
      "repo_id": "Qwen/Qwen3-1.7B",
      "access_type": "ACCESS_TYPE_PUBLIC"
    },
    "description": "qwen base model",
    "preferred_gpu_region": null,
    "accept_terms_and_conditions": true,
    "tags": {
      "tags": ["base-model"]
    }
  }'

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

ratelimit-reset integer

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

Response Schema: application/json

error string optional

Example: example string

import_job object optional

Import job tracking for a custom model

Show child properties

bytes_done string (uint64) optional

Example: 12345

Bytes imported so far

bytes_total string (uint64) optional

Example: 12345

Total bytes to import

completed_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the import completed

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the job was created

error_message string optional

Example: example string

Error message if import failed

error_step string optional

Example: example string

Step at which the error occurred

files_done integer (int64) optional

Example: 123

Number of files imported so far

files_total integer (int64) optional

Example: 123

Total number of files to import

started_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the import started

status string optional

Example: example string

Current status of the import job

uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier for the import job

model object optional

Custom model - user-imported model from HuggingFace, Spaces, etc.

Show child properties

active_deployments array of object optional

List of active deployments using this model

Show child properties

created_at string optional

Example: example string

RFC 3339 timestamp indicating when the dedicated inference deployment was created

endpoints object optional

Endpoint URLs for a dedicated inference deployment associated with a custom model.

Show child properties

private_endpoint_fqdn string optional

Example: example string

Private FQDN for the deployment

public_endpoint_fqdn string optional

Example: example string

Public FQDN for the deployment

id string optional

Example: example string

Unique identifier (UUID) of the dedicated inference deployment

name string optional

Example: example name

Human-readable name of the dedicated inference deployment

region_slug string optional

Example: example string

Slug of the region where the dedicated inference deployment is running (e.g. "atl1")

state string optional

Example: example string

Current lifecycle state of the dedicated inference deployment (e.g. "ACTIVE", "PROVISIONING")

updated_at string optional

Example: 2023-01-01

RFC 3339 timestamp indicating when the dedicated inference deployment was last updated

architecture string optional

Example: example string

Model architecture type (free-form string from config.json)

config_json object optional

Raw config.json contents from the model repository

context_length integer (int64) optional

Example: 123

Maximum context length supported by the model

cost_estimate_per_month integer (int64) optional

Example: 123

Estimated monthly cost in dollars for hosting

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the model was created

description string optional

Example: example string

Description of the custom model

file_count integer (int64) optional

Example: 123

Number of files in the model

input_modalities array of string optional

Example: ["example string"]

Input modalities supported (e.g., text, image)

license string optional

Example: example string

License under which the model is distributed

name string optional

Example: example name

Name of the custom model

output_modalities array of string optional

Example: ["example string"]

Output modalities supported (e.g., text, image)

parameters string (uint64) optional

Example: 12345

Number of parameters in the model

source_ref object optional

Reference to the original source of the model

Show child properties

access_type string, one of: ACCESS_TYPE_UNSPECIFIED, ACCESS_TYPE_PUBLIC, ACCESS_TYPE_PRIVATE, ACCESS_TYPE_GATED optional

Example: ACCESS_TYPE_UNSPECIFIED

Access level required for the model repository

bucket string optional

Example: example string

Spaces bucket name

commit_sha string optional

Example: example string

Git commit SHA of the model version

hf_token string optional

Example: example string

User-provided HuggingFace token for gated/private models (not persisted in source_ref)

prefix string optional

Example: example string

Object prefix path in the bucket

region string optional

Example: example string

Spaces bucket region

repo_id string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Huggingface repository identifier

source_type string, one of: SOURCE_TYPE_UNSPECIFIED, SOURCE_TYPE_HUGGINGFACE, SOURCE_TYPE_SPACES_BUCKET, SOURCE_TYPE_SDK_UPLOAD, SOURCE_TYPE_FINE_TUNING optional

Example: SOURCE_TYPE_UNSPECIFIED

Source from which the model was imported

status string, one of: STATUS_UNSPECIFIED, STATUS_IMPORTING, STATUS_READY, STATUS_FAILED, STATUS_DELETED optional

Example: STATUS_UNSPECIFIED

Import and deployment status of the custom model

storage_region string optional

Example: example string

Region of the Spaces bucket where model files are stored

tags object optional

User-defined tags for organizing models

Show child properties

tags array of string optional

Example: ["example string"]

List of tag strings

team_id string (uint64) optional

Example: 12345

Team that owns the model

total_size_bytes string (uint64) optional

Example: 12345

Total size of model files in bytes

updated_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the model was last updated

uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier for the custom model

validation_steps array of object optional

Validation steps performed during import

Show child properties

error string optional

Example: example string

Error message if validation failed

name string optional

Example: example name

Name of the validation step

passed boolean optional

Example: true

Whether the validation step passed

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "error": "example string",
  "import_job": {
    "bytes_done": "12345",
    "bytes_total": "12345",
    "completed_at": "2023-01-01T00:00:00Z",
    "created_at": "2023-01-01T00:00:00Z",
    "error_message": "example string",
    "error_step": "example string",
    "files_done": 123,
    "files_total": 123,
    "started_at": "2023-01-01T00:00:00Z",
    "status": "example string",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "model": {
    "active_deployments": [],
    "architecture": "example string",
    "context_length": 123,
    "cost_estimate_per_month": 123,
    "created_at": "2023-01-01T00:00:00Z",
    "description": "example string",
    "file_count": 123,
    "input_modalities": [
      "example string"
    ],
    "license": "example string",
    "name": "example name",
    "output_modalities": [
      "example string"
    ],
    "parameters": "12345",
    "source_ref": {
      "access_type": "ACCESS_TYPE_UNSPECIFIED",
      "bucket": "example string",
      "commit_sha": "example string",
      "hf_token": "example string",
      "prefix": "example string",
      "region": "example string",
      "repo_id": "123e4567-e89b-12d3-a456-426614174000"
    },
    "source_type": "SOURCE_TYPE_UNSPECIFIED",
    "status": "STATUS_UNSPECIFIED",
    "storage_region": "example string",
    "tags": {
      "tags": [
        "example string"
      ]
    },
    "team_id": "12345",
    "total_size_bytes": "12345",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "validation_steps": [
    {
      "error": "example string",
      "name": "example name",
      "passed": true
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET Get Custom Model

/v2/gen-ai/custom_models/{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.

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.

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

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`

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 custom model, send a GET request to /v2/gen-ai/custom_models/{uuid}.

Path Parameters

uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

UUID of the custom model to retrieve

Request: `/v2/gen-ai/custom_models/{uuid}`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/custom_models/11f13e07-1e4f-1325-b542-ca68c578b04b"

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

ratelimit-reset integer

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

Response Schema: application/json

model object optional

Custom model - user-imported model from HuggingFace, Spaces, etc.

Show child properties

active_deployments array of object optional

List of active deployments using this model

Show child properties

created_at string optional

Example: example string

RFC 3339 timestamp indicating when the dedicated inference deployment was created

endpoints object optional

Endpoint URLs for a dedicated inference deployment associated with a custom model.

Show child properties

private_endpoint_fqdn string optional

Example: example string

Private FQDN for the deployment

public_endpoint_fqdn string optional

Example: example string

Public FQDN for the deployment

id string optional

Example: example string

Unique identifier (UUID) of the dedicated inference deployment

name string optional

Example: example name

Human-readable name of the dedicated inference deployment

region_slug string optional

Example: example string

Slug of the region where the dedicated inference deployment is running (e.g. "atl1")

state string optional

Example: example string

Current lifecycle state of the dedicated inference deployment (e.g. "ACTIVE", "PROVISIONING")

updated_at string optional

Example: 2023-01-01

RFC 3339 timestamp indicating when the dedicated inference deployment was last updated

architecture string optional

Example: example string

Model architecture type (free-form string from config.json)

config_json object optional

Raw config.json contents from the model repository

context_length integer (int64) optional

Example: 123

Maximum context length supported by the model

cost_estimate_per_month integer (int64) optional

Example: 123

Estimated monthly cost in dollars for hosting

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the model was created

description string optional

Example: example string

Description of the custom model

file_count integer (int64) optional

Example: 123

Number of files in the model

input_modalities array of string optional

Example: ["example string"]

Input modalities supported (e.g., text, image)

license string optional

Example: example string

License under which the model is distributed

name string optional

Example: example name

Name of the custom model

output_modalities array of string optional

Example: ["example string"]

Output modalities supported (e.g., text, image)

parameters string (uint64) optional

Example: 12345

Number of parameters in the model

source_ref object optional

Reference to the original source of the model

Show child properties

access_type string, one of: ACCESS_TYPE_UNSPECIFIED, ACCESS_TYPE_PUBLIC, ACCESS_TYPE_PRIVATE, ACCESS_TYPE_GATED optional

Example: ACCESS_TYPE_UNSPECIFIED

Access level required for the model repository

bucket string optional

Example: example string

Spaces bucket name

commit_sha string optional

Example: example string

Git commit SHA of the model version

hf_token string optional

Example: example string

User-provided HuggingFace token for gated/private models (not persisted in source_ref)

prefix string optional

Example: example string

Object prefix path in the bucket

region string optional

Example: example string

Spaces bucket region

repo_id string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Huggingface repository identifier

source_type string, one of: SOURCE_TYPE_UNSPECIFIED, SOURCE_TYPE_HUGGINGFACE, SOURCE_TYPE_SPACES_BUCKET, SOURCE_TYPE_SDK_UPLOAD, SOURCE_TYPE_FINE_TUNING optional

Example: SOURCE_TYPE_UNSPECIFIED

Source from which the model was imported

status string, one of: STATUS_UNSPECIFIED, STATUS_IMPORTING, STATUS_READY, STATUS_FAILED, STATUS_DELETED optional

Example: STATUS_UNSPECIFIED

Import and deployment status of the custom model

storage_region string optional

Example: example string

Region of the Spaces bucket where model files are stored

tags object optional

User-defined tags for organizing models

Show child properties

tags array of string optional

Example: ["example string"]

List of tag strings

team_id string (uint64) optional

Example: 12345

Team that owns the model

total_size_bytes string (uint64) optional

Example: 12345

Total size of model files in bytes

updated_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the model was last updated

uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier for the custom model

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "model": {
    "active_deployments": [],
    "architecture": "example string",
    "context_length": 123,
    "cost_estimate_per_month": 123,
    "created_at": "2023-01-01T00:00:00Z",
    "description": "example string",
    "file_count": 123,
    "input_modalities": [
      "example string"
    ],
    "license": "example string",
    "name": "example name",
    "output_modalities": [
      "example string"
    ],
    "parameters": "12345",
    "source_ref": {
      "access_type": "ACCESS_TYPE_UNSPECIFIED",
      "bucket": "example string",
      "commit_sha": "example string",
      "hf_token": "example string",
      "prefix": "example string",
      "region": "example string",
      "repo_id": "123e4567-e89b-12d3-a456-426614174000"
    },
    "source_type": "SOURCE_TYPE_UNSPECIFIED",
    "status": "STATUS_UNSPECIFIED",
    "storage_region": "example string",
    "tags": {
      "tags": [
        "example string"
      ]
    },
    "team_id": "12345",
    "total_size_bytes": "12345",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete Custom Model

/v2/gen-ai/custom_models/{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.

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.

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

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`

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 custom model, send a DELETE request to /v2/genai/custom_models/{uuid}.

Path Parameters

uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

UUID of the custom model to delete

Request: `/v2/gen-ai/custom_models/{uuid}`

cURL

curl -X DELETE \
  --header "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/custom_models/11f13e07-1e4f-1325-b542-ca68c578b04b"

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

ratelimit-reset integer

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

Response Schema: application/json

error string optional

Example: example string

Error message if deletion failed

status string, one of: DELETE_CUSTOM_MODEL_STATUS_UNSPECIFIED, DELETE_CUSTOM_MODEL_STATUS_SUCCESS, DELETE_CUSTOM_MODEL_STATUS_FAIL optional

Example: DELETE_CUSTOM_MODEL_STATUS_UNSPECIFIED

Status of delete operation

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "error": "example string",
  "status": "DELETE_CUSTOM_MODEL_STATUS_UNSPECIFIED"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

PATCH Update Custom Model Metadata

/v2/gen-ai/custom_models/{uuid}/metadata

Authorizations: bearer_auth (1 scope)

Http: Bearer

Required scopes: genai:default

OAuth Authentication

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

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.

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

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`

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 custom model metadata, send a PATCH request to /v2/gen-ai/custom_models/{uuid}/metadata.

Path Parameters

uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

UUID of the custom model to update

Request Body: `application/json`

description string optional

Example: example string

name string optional

Example: example name

tags object optional

User-defined tags for organizing models

Show child properties

tags array of string optional

Example: ["example string"]

List of tag strings

uuid string optional

Example: a1b2c3d4-...

UUID of the custom model to update

Request: `/v2/gen-ai/custom_models/{uuid}/metadata`

Payload

Content type application/json

{
  "description": "example string",
  "name": "example name",
  "tags": {
    "tags": [
      "example string"
    ]
  },
  "uuid": "a1b2c3d4-..."
}

cURL

curl -X PATCH \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/custom_models/11f13d93-a879-c342-b542-ca68c578b04b/metadata" \
  -d '{
    "description": "finetuned model with olympiad math data",
    "tags": {
      "tags": ["finetuned", "new"]
    }
  }'

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

ratelimit-reset integer

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

Response Schema: application/json

model object optional

Custom model - user-imported model from HuggingFace, Spaces, etc.

Show child properties

active_deployments array of object optional

List of active deployments using this model

Show child properties

created_at string optional

Example: example string

RFC 3339 timestamp indicating when the dedicated inference deployment was created

endpoints object optional

Endpoint URLs for a dedicated inference deployment associated with a custom model.

Show child properties

private_endpoint_fqdn string optional

Example: example string

Private FQDN for the deployment

public_endpoint_fqdn string optional

Example: example string

Public FQDN for the deployment

id string optional

Example: example string

Unique identifier (UUID) of the dedicated inference deployment

name string optional

Example: example name

Human-readable name of the dedicated inference deployment

region_slug string optional

Example: example string

Slug of the region where the dedicated inference deployment is running (e.g. "atl1")

state string optional

Example: example string

Current lifecycle state of the dedicated inference deployment (e.g. "ACTIVE", "PROVISIONING")

updated_at string optional

Example: 2023-01-01

RFC 3339 timestamp indicating when the dedicated inference deployment was last updated

architecture string optional

Example: example string

Model architecture type (free-form string from config.json)

config_json object optional

Raw config.json contents from the model repository

context_length integer (int64) optional

Example: 123

Maximum context length supported by the model

cost_estimate_per_month integer (int64) optional

Example: 123

Estimated monthly cost in dollars for hosting

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the model was created

description string optional

Example: example string

Description of the custom model

file_count integer (int64) optional

Example: 123

Number of files in the model

input_modalities array of string optional

Example: ["example string"]

Input modalities supported (e.g., text, image)

license string optional

Example: example string

License under which the model is distributed

name string optional

Example: example name

Name of the custom model

output_modalities array of string optional

Example: ["example string"]

Output modalities supported (e.g., text, image)

parameters string (uint64) optional

Example: 12345

Number of parameters in the model

source_ref object optional

Reference to the original source of the model

Show child properties

access_type string, one of: ACCESS_TYPE_UNSPECIFIED, ACCESS_TYPE_PUBLIC, ACCESS_TYPE_PRIVATE, ACCESS_TYPE_GATED optional

Example: ACCESS_TYPE_UNSPECIFIED

Access level required for the model repository

bucket string optional

Example: example string

Spaces bucket name

commit_sha string optional

Example: example string

Git commit SHA of the model version

hf_token string optional

Example: example string

User-provided HuggingFace token for gated/private models (not persisted in source_ref)

prefix string optional

Example: example string

Object prefix path in the bucket

region string optional

Example: example string

Spaces bucket region

repo_id string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Huggingface repository identifier

source_type string, one of: SOURCE_TYPE_UNSPECIFIED, SOURCE_TYPE_HUGGINGFACE, SOURCE_TYPE_SPACES_BUCKET, SOURCE_TYPE_SDK_UPLOAD, SOURCE_TYPE_FINE_TUNING optional

Example: SOURCE_TYPE_UNSPECIFIED

Source from which the model was imported

status string, one of: STATUS_UNSPECIFIED, STATUS_IMPORTING, STATUS_READY, STATUS_FAILED, STATUS_DELETED optional

Example: STATUS_UNSPECIFIED

Import and deployment status of the custom model

storage_region string optional

Example: example string

Region of the Spaces bucket where model files are stored

tags object optional

User-defined tags for organizing models

Show child properties

tags array of string optional

Example: ["example string"]

List of tag strings

team_id string (uint64) optional

Example: 12345

Team that owns the model

total_size_bytes string (uint64) optional

Example: 12345

Total size of model files in bytes

updated_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the model was last updated

uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier for the custom model

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "model": {
    "active_deployments": [],
    "architecture": "example string",
    "context_length": 123,
    "cost_estimate_per_month": 123,
    "created_at": "2023-01-01T00:00:00Z",
    "description": "example string",
    "file_count": 123,
    "input_modalities": [
      "example string"
    ],
    "license": "example string",
    "name": "example name",
    "output_modalities": [
      "example string"
    ],
    "parameters": "12345",
    "source_ref": {
      "access_type": "ACCESS_TYPE_UNSPECIFIED",
      "bucket": "example string",
      "commit_sha": "example string",
      "hf_token": "example string",
      "prefix": "example string",
      "region": "example string",
      "repo_id": "123e4567-e89b-12d3-a456-426614174000"
    },
    "source_type": "SOURCE_TYPE_UNSPECIFIED",
    "status": "STATUS_UNSPECIFIED",
    "storage_region": "example string",
    "tags": {
      "tags": [
        "example string"
      ]
    },
    "team_id": "12345",
    "total_size_bytes": "12345",
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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, EVALUATION_DATASET_TYPE_MODEL 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`

Payload

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "evaluation_dataset_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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`

Payload

Content type application/json

{
  "files": [
    {
      "file_name": "example name",
      "file_size": "12345"
    }
  ]
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET Get Download URL for Evaluation Dataset

/v2/gen-ai/evaluation_datasets/{dataset_uuid}/download_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.

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.

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

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`

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 presigned download URL for an evaluation dataset, send a GET request to /v2/genai/evaluation_datasets/{dataset_uuid}/download_url.

Path Parameters

dataset_uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

UUID of the evaluation dataset.

Request: `/v2/gen-ai/evaluation_datasets/{dataset_uuid}/download_url`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/evaluation_datasets/123e4567-e89b-12d3-a456-426614174000/download_url"

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

ratelimit-reset integer

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

Response Schema: application/json

download_url string optional

Example: example string

The presigned URL to download the dataset file.

expires_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

The time the URL expires at.

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "download_url": "example string",
  "expires_at": "2023-01-01T00:00:00Z"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "metrics": [
    {
      "category": "METRIC_CATEGORY_UNSPECIFIED",
      "description": "example string",
      "evaluation_scope": "EVALUATION_SCOPE_UNSPECIFIED",
      "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
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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`

Payload

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "evaluation_run_uuids": [
    "example string"
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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.

spans array of object optional

Child spans - must contain between 1 and 999 spans Allowed types: agent, llm, tool, retriever (not workflow)

Show child properties

agent object optional

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

When the span was created

input object optional

Input data for the span (flexible structure - can be messages array, string, etc.)

Additional nested properties not shown. Refer to the full API spec for details.

llm object optional

LLM span

Additional nested properties not shown. Refer to the full API spec for details.

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

Additional nested properties not shown. Refer to the full API spec for details.

retriever object optional

Retriever span

Additional nested properties not shown. Refer to the full API spec for details.

tool object optional

Tool span

Additional nested properties not shown. Refer to the full API spec for details.

type string (enum) optional

Example: TRACE_SPAN_TYPE_UNKNOWN

Types of spans in a trace

workflow object optional

Workflow span - can contain child spans (agent, llm, tool, retriever)

Additional nested properties not shown. Refer to the full API spec for details.

type string (enum) 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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.

spans array of object optional

Child spans - must contain between 1 and 999 spans Allowed types: agent, llm, tool, retriever (not workflow)

Show child properties

agent object optional

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

When the span was created

input object optional

Input data for the span (flexible structure - can be messages array, string, etc.)

Additional nested properties not shown. Refer to the full API spec for details.

llm object optional

LLM span

Additional nested properties not shown. Refer to the full API spec for details.

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

Additional nested properties not shown. Refer to the full API spec for details.

retriever object optional

Retriever span

Additional nested properties not shown. Refer to the full API spec for details.

tool object optional

Tool span

Additional nested properties not shown. Refer to the full API spec for details.

type string (enum) optional

Example: TRACE_SPAN_TYPE_UNKNOWN

Types of spans in a trace

workflow object optional

Workflow span - can contain child spans (agent, llm, tool, retriever)

Additional nested properties not shown. Refer to the full API spec for details.

type string (enum) 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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_type string, one of: EVALUATION_DATASET_TYPE_UNKNOWN, EVALUATION_DATASET_TYPE_ADK, EVALUATION_DATASET_TYPE_NON_ADK, EVALUATION_DATASET_TYPE_MODEL optional

Example: EVALUATION_DATASET_TYPE_UNKNOWN

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

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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`

Payload

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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_type string, one of: EVALUATION_DATASET_TYPE_UNKNOWN, EVALUATION_DATASET_TYPE_ADK, EVALUATION_DATASET_TYPE_NON_ADK, EVALUATION_DATASET_TYPE_MODEL optional

Example: EVALUATION_DATASET_TYPE_UNKNOWN

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

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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_type": "EVALUATION_DATASET_TYPE_UNKNOWN",
      "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

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

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.

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

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`

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}`

Payload

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

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

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

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

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

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

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "version": 123
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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`

Payload

Content type application/json

{
  "data_source_uuids": [
    "example string"
  ],
  "knowledge_base_uuid": "\"12345678-1234-1234-1234-123456789012\""
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "signed_url": "example string"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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`

Payload

Content type application/json

{
  "uuid": "\"12345678-1234-1234-1234-123456789012\""
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

previous string optional

Example: example string

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

Optional data sources to attach at creation. Omit or use an empty list to create the knowledge base without sources, then add sources (with chunking strategy and sizes) using Add a Data Source to a Knowledge Base. When provided, see Organize Data Sources for 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_UNKNOWN

chunking_options object optional

Show child properties

child_chunk_size integer (int64) optional

Example: 350

max_chunk_size integer (int64) optional

Example: 750

Common 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.

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

size string, one of: OPEN_SEARCH_PLAN_SIZE_UNSPECIFIED, OPEN_SEARCH_PLAN_SIZE_SMALL, OPEN_SEARCH_PLAN_SIZE_MEDIUM, OPEN_SEARCH_PLAN_SIZE_LARGE, OPEN_SEARCH_PLAN_SIZE_EXTRA_LARGE optional

Example: OPEN_SEARCH_PLAN_SIZE_UNSPECIFIED

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`

Payload

Content type application/json

{
  "database_id": "\"12345678-1234-1234-1234-123456789012\"",
  "datasources": [
    {
      "bucket_name": "example name",
      "bucket_region": "example string",
      "chunking_algorithm": "CHUNKING_ALGORITHM_UNKNOWN",
      "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\"",
  "reranking_config": {
    "enabled": true,
    "model": "\"bge-reranker-v2-m3\""
  },
  "size": "OPEN_SEARCH_PLAN_SIZE_UNSPECIFIED",
  "tags": [
    "example string"
  ],
  "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\""
}

cURL

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",
    "reranking_config": {
      "enabled": true,
      "model": "bge-reranker-v2-m3"
    }
  }'

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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",
    "reranking_config": {
      "enabled": true,
      "model": "\"bge-reranker-v2-m3\""
    },
    "tags": [
      "example string"
    ],
    "updated_at": "2023-01-01T00:00:00Z",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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`

Payload

Content type application/json

{
  "files": [
    {
      "file_name": "example name",
      "file_size": "12345"
    }
  ]
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

Example: CHUNKING_ALGORITHM_UNKNOWN

chunking_options object optional

Show child properties

child_chunk_size integer (int64) optional

Example: 350

max_chunk_size integer (int64) optional

Example: 750

Common 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

previous string optional

Example: example string

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "knowledge_base_data_sources": [
    {
      "bucket_name": "example name",
      "chunking_algorithm": "CHUNKING_ALGORITHM_UNKNOWN",
      "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

Example: CHUNKING_ALGORITHM_UNKNOWN

chunking_options object optional

Show child properties

child_chunk_size integer (int64) optional

Example: 350

max_chunk_size integer (int64) optional

Example: 750

Common 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`

Payload

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_UNKNOWN",
  "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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

Example: CHUNKING_ALGORITHM_UNKNOWN

chunking_options object optional

Show child properties

child_chunk_size integer (int64) optional

Example: 350

max_chunk_size integer (int64) optional

Example: 750

Common 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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_UNKNOWN",
    "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"
      ]
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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`

Example: CHUNKING_ALGORITHM_UNKNOWN

chunking_options object optional

Show child properties

child_chunk_size integer (int64) optional

Example: 350

max_chunk_size integer (int64) optional

Example: 750

Common 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}`

Payload

Content type application/json

{
  "chunking_algorithm": "CHUNKING_ALGORITHM_UNKNOWN",
  "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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

Example: CHUNKING_ALGORITHM_UNKNOWN

chunking_options object optional

Show child properties

child_chunk_size integer (int64) optional

Example: 350

max_chunk_size integer (int64) optional

Example: 750

Common 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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_UNKNOWN",
    "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"
      ]
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "data_source_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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",
    "reranking_config": {
      "enabled": true,
      "model": "\"bge-reranker-v2-m3\""
    },
    "tags": [
      "example string"
    ],
    "updated_at": "2023-01-01T00:00:00Z",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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, optional.

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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}`

Payload

Content type application/json

{
  "database_id": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"My Knowledge Base\"",
  "project_id": "\"12345678-1234-1234-1234-123456789012\"",
  "reranking_config": {
    "enabled": true,
    "model": "\"bge-reranker-v2-m3\""
  },
  "tags": [
    "example string"
  ],
  "uuid": "\"12345678-1234-1234-1234-123456789012\""
}

cURL

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",
    "reranking_config": {
      "enabled": true,
      "model": "bge-reranker-v2-m3"
    }
  }'

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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",
    "reranking_config": {
      "enabled": true,
      "model": "\"bge-reranker-v2-m3\""
    },
    "tags": [
      "example string"
    ],
    "updated_at": "2023-01-01T00:00:00Z",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Create Presigned URLs for Model Evaluation Dataset File Upload

/v2/gen-ai/model_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.

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.

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

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`

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 model evaluation dataset file upload, send a POST request to /v2/genai/model_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/model_evaluation/datasets/file_upload_presigned_urls`

Payload

Content type application/json

{
  "files": [
    {
      "file_name": "example name",
      "file_size": "12345"
    }
  ]
}

cURL

curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/model_evaluation/datasets/file_upload_presigned_urls" \
  -d '{
    "files": [{
      "file_name": "dataset.jsonl",
      "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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET List Model Evaluation Metrics

/v2/gen-ai/model_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.

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.

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

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`

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 available metrics for model evaluation, send a GET request to /v2/genai/model_evaluation_metrics.

Request: `/v2/gen-ai/model_evaluation_metrics`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/model_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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

List of model evaluation metrics

Show child properties

category string (enum) optional

Example: METRIC_CATEGORY_UNSPECIFIED

description string optional

Example: example string

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "metrics": [
    {
      "category": "METRIC_CATEGORY_UNSPECIFIED",
      "description": "example string",
      "evaluation_scope": "EVALUATION_SCOPE_UNSPECIFIED",
      "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
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET List Model Evaluation Presets

/v2/gen-ai/model_evaluation_presets

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.

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.

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

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`

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 saved model evaluation presets, send a GET request to /v2/genai/model_evaluation_presets.

Request: `/v2/gen-ai/model_evaluation_presets`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/model_evaluation_presets"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

presets array of object optional

List of explicitly saved evaluation presets (reusable configs).

Show child properties

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the preset was created.

dataset_name string optional

Example: example name

dataset_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Dataset used for evaluation.

eval_preset_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the evaluation preset.

judge_model_name string optional

Example: example name

judge_model_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Judge model used to score responses.

metrics array of object optional

Metrics selected for this preset.

Show child properties

category string (enum) optional

Example: METRIC_CATEGORY_UNSPECIFIED

description string optional

Example: example string

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

Name of the evaluation preset.

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.

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "presets": [
    {
      "created_at": "2023-01-01T00:00:00Z",
      "dataset_name": "example name",
      "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "eval_preset_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "judge_model_name": "example name",
      "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "metrics": [],
      "name": "example name"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Model Evaluation Preset

/v2/gen-ai/model_evaluation_presets/{eval_preset_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.

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.

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

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`

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 a saved model evaluation preset, send a GET request to /v2/genai/model_evaluation_presets/{eval_preset_uuid}.

Path Parameters

eval_preset_uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

UUID of the evaluation preset.

Request: `/v2/gen-ai/model_evaluation_presets/{eval_preset_uuid}`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/model_evaluation_presets/123e4567-e89b-12d3-a456-426614174000"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

preset object optional

Model Evaluation Preset - a saved, reusable configuration for model evaluation runs.

Show child properties

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the preset was created.

dataset_name string optional

Example: example name

dataset_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Dataset used for evaluation.

eval_preset_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the evaluation preset.

judge_model_name string optional

Example: example name

judge_model_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Judge model used to score responses.

metrics array of object optional

Metrics selected for this preset.

Show child properties

category string (enum) optional

Example: METRIC_CATEGORY_UNSPECIFIED

description string optional

Example: example string

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

Name of the evaluation preset.

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.

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "preset": {
    "created_at": "2023-01-01T00:00:00Z",
    "dataset_name": "example name",
    "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "eval_preset_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "judge_model_name": "example name",
    "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "metrics": [],
    "name": "example name",
    "star_metric": {
      "metric_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "name": "example name",
      "success_threshold": 123,
      "success_threshold_pct": 123
    }
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET List Model Evaluation Runs

/v2/gen-ai/model_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.

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.

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

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`

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 model evaluation runs, send a GET request to /v2/genai/model_evaluation_runs.

Query Parameters

eval_preset_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the evaluation preset to filter by.

status string (enum) optional

Example: MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED

Filter by evaluation run status.

Default: MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED

page integer optional

Example: 1

Page number.

per_page integer optional

Example: 1

Items per page.

Request: `/v2/gen-ai/model_evaluation_runs`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/model_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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

runs array of object optional

Summary view of evaluation runs for the run history list.

Show child properties

candidate_model_name string optional

Example: example name

Name of the candidate model being evaluated.

candidate_model_source string, one of: CANDIDATE_MODEL_SOURCE_SERVERLESS, CANDIDATE_MODEL_SOURCE_DEDICATED, CANDIDATE_MODEL_SOURCE_ROUTER optional

Example: CANDIDATE_MODEL_SOURCE_SERVERLESS

Whether inference runs against the serverless platform, a dedicated deployment, or a model router.

candidate_model_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the candidate model being evaluated.

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Timestamp when the run was created.

dataset_name string optional

Example: example name

Name of the dataset used for evaluation.

dataset_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the dataset used for evaluation.

eval_run_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the evaluation run.

judge_model_name string optional

Example: example name

judge_model_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Judge model used to score responses.

name string optional

Example: example name

Name of the evaluation run.

status string (enum) optional

Example: MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED

Model Evaluation Run Statuses

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  },
  "runs": [
    {
      "candidate_model_name": "example name",
      "candidate_model_source": "CANDIDATE_MODEL_SOURCE_SERVERLESS",
      "candidate_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "dataset_name": "example name",
      "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "eval_run_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "judge_model_name": "example name",
      "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "name": "example name",
      "status": "MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Create Model Evaluation Run

/v2/gen-ai/model_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.

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.

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

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`

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 evaluation run, send a POST request to /v2/genai/model_evaluation_runs.

Request Body: `application/json`

candidate_inference_config object optional

Inference configuration for the candidate model during evaluation.

Show child properties

max_tokens integer (int64) optional

Example: 123

stop_token string optional

Example: example string

system_prompt string optional

Example: example string

temperature number (float) optional

Example: 123

candidate_model_name string optional

Example: example name

Model slug used to call the candidate model API. For dedicated inference, this is the model slug from the deployment. For serverless, this should match the model's internal name.

candidate_model_source string, one of: CANDIDATE_MODEL_SOURCE_SERVERLESS, CANDIDATE_MODEL_SOURCE_DEDICATED, CANDIDATE_MODEL_SOURCE_ROUTER optional

Example: CANDIDATE_MODEL_SOURCE_SERVERLESS

Whether inference runs against the serverless platform, a dedicated deployment, or a model router.

candidate_model_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the candidate model to evaluate.

dataset_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the dataset to use for evaluation.

eval_preset_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

judge_model_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the judge model used to score responses.

metric_uuids array of string optional

Example: ["example string"]

UUIDs of metrics to evaluate (selected from ListModelEvaluationMetrics).

name string optional

Example: example name

preset_name string optional

Example: example name

save_as_preset boolean optional

Example: true

If true, saves the inline config as a reusable preset
Ignored when eval_preset_uuid is provided.

source string optional

Example: example string

Source of the run creation (api, sdk, cli).

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.

Request: `/v2/gen-ai/model_evaluation_runs`

Payload

Content type application/json

{
  "candidate_inference_config": {
    "max_tokens": 123,
    "stop_token": "example string",
    "system_prompt": "example string",
    "temperature": 123
  },
  "candidate_model_name": "example name",
  "candidate_model_source": "CANDIDATE_MODEL_SOURCE_SERVERLESS",
  "candidate_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "eval_preset_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "metric_uuids": [
    "example string"
  ],
  "name": "example name",
  "preset_name": "example name",
  "save_as_preset": true,
  "source": "example string",
  "star_metric": {
    "metric_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "example name",
    "success_threshold": 123,
    "success_threshold_pct": 123
  }
}

cURL

curl -X POST \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/model_evaluation_runs" \
  -d '{
    "name": "my-evaluation-run",
    "candidate_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "judge_model_uuid": "223e4567-e89b-12d3-a456-426614174001",
    "dataset_uuid": "323e4567-e89b-12d3-a456-426614174002",
    "metric_uuids": [
      "423e4567-e89b-12d3-a456-426614174003"
    ]
  }'

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

eval_run_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the created evaluation run.

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "eval_run_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Model Evaluation Run

/v2/gen-ai/model_evaluation_runs/{eval_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.

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.

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

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`

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 a model evaluation run, send a GET request to /v2/genai/model_evaluation_runs/{eval_run_uuid}.

Path Parameters

eval_run_uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

UUID of the evaluation run.

Query Parameters

page integer optional

Example: 1

Page number for per-prompt results (defaults to 1).

per_page integer optional

Example: 1

Number of per-prompt results per page (defaults to 50).

Request: `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/model_evaluation_runs/123e4567-e89b-12d3-a456-426614174000"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

results array of object optional

Paginated per-prompt evaluation results.

Show child properties

candidate_model_name string optional

Example: example name

candidate_model_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

ground_truth string optional

Example: example string

input string optional

Example: example string

The input query sent to the candidate model.

metric_results array of object optional

Per-metric scores and judge reasoning for this 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.

output string optional

Example: example string

The response from the candidate model.

run object optional

Model Evaluation Run Detail - full view returned when fetching a specific run.

Show child properties

candidate_inference_config object optional

Inference configuration for the candidate model during evaluation.

Show child properties

max_tokens integer (int64) optional

Example: 123

stop_token string optional

Example: example string

system_prompt string optional

Example: example string

temperature number (float) optional

Example: 123

candidate_model_name string optional

Example: example name

candidate_model_source string, one of: CANDIDATE_MODEL_SOURCE_SERVERLESS, CANDIDATE_MODEL_SOURCE_DEDICATED, CANDIDATE_MODEL_SOURCE_ROUTER optional

Example: CANDIDATE_MODEL_SOURCE_SERVERLESS

Whether inference runs against the serverless platform, a dedicated deployment, or a model router.

candidate_model_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Candidate model being evaluated.

completed_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

dataset_name string optional

Example: example name

dataset_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Dataset used for the evaluation.

error_description string optional

Example: example string

Error description if the run failed or partially succeeded.

eval_preset_name string optional

Example: example name

eval_preset_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

eval_run_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the evaluation run.

judge_model_name string optional

Example: example name

judge_model_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Judge model used to score responses.

metrics array of object optional

Metrics selected for this evaluation.

Show child properties

category string (enum) optional

Example: METRIC_CATEGORY_UNSPECIFIED

description string optional

Example: example string

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

Name of the evaluation run.

result_summary object optional

Aggregated result summary for a completed model evaluation run.

Show child properties

end_time string (date-time) optional

Example: 2023-01-01T00:00:00Z

metric_summaries array of object optional

Per-metric aggregated pass/fail statistics.

Show child properties

description string optional

Example: example string

fail_percent number (double) optional

Example: 123

metric_name string optional

Example: example name

metric_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

pass_percent number (double) optional

Example: 123

overall_score_percent number (double) optional

Example: 123

per_model_summaries object optional

Wrapper for per-model summaries, used inside a oneof on ModelEvaluationRunResultSummary.

Show child properties

summaries array of object optional

Additional nested properties not shown. Refer to the full API spec for details.

performance_metrics object optional

All performance metrics are for the candidate model unless noted otherwise.

Show child properties

candidate_latency object optional

Latency metrics for candidate model invocations (in milliseconds).

Additional nested properties not shown. Refer to the full API spec for details.

token_usage object optional

Additional nested properties not shown. Refer to the full API spec for details.

pricing object optional

Pricing breakdown for an evaluation run.

Show child properties

currency string optional

Example: example string

Currency code (e.g., "USD").

judge_model_pricing object optional

Token pricing breakdown for a single model.

Additional nested properties not shown. Refer to the full API spec for details.

per_candidate_model_pricing array of object optional

Pricing per candidate model.

Additional nested properties not shown. Refer to the full API spec for details.

total_cost number (double) optional

Example: 123

Total cost of the evaluation run (all candidates + judge).

star_metric_summary object optional

Star metric summary with identifying details and threshold.

Show child properties

metric_name string optional

Example: example name

metric_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

threshold number (float) optional

Example: 123

start_time string (date-time) optional

Example: 2023-01-01T00:00:00Z

Run timing.

total_duration_seconds integer (int64) optional

Example: 123

Total wall-clock duration in seconds.

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.

started_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

status string (enum) optional

Example: MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED

Model Evaluation Run Statuses

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  },
  "results": [
    {
      "candidate_model_name": "example name",
      "candidate_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "ground_truth": "example string",
      "input": "example string",
      "metric_results": [],
      "output": "example string"
    }
  ],
  "run": {
    "candidate_inference_config": {
      "max_tokens": 123,
      "stop_token": "example string",
      "system_prompt": "example string",
      "temperature": 123
    },
    "candidate_model_name": "example name",
    "candidate_model_source": "CANDIDATE_MODEL_SOURCE_SERVERLESS",
    "candidate_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "completed_at": "2023-01-01T00:00:00Z",
    "created_at": "2023-01-01T00:00:00Z",
    "dataset_name": "example name",
    "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "error_description": "example string",
    "eval_preset_name": "example name",
    "eval_preset_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "eval_run_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "judge_model_name": "example name",
    "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "metrics": [],
    "name": "example name",
    "result_summary": {
      "end_time": "2023-01-01T00:00:00Z",
      "metric_summaries": [],
      "overall_score_percent": 123,
      "start_time": "2023-01-01T00:00:00Z",
      "total_duration_seconds": 123
    },
    "star_metric": {
      "metric_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "name": "example name",
      "success_threshold": 123,
      "success_threshold_pct": 123
    },
    "started_at": "2023-01-01T00:00:00Z",
    "status": "MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete Model Evaluation Run

/v2/gen-ai/model_evaluation_runs/{eval_run_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.

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.

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

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`

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 model evaluation run, send a DELETE request to /v2/gen-ai/model_evaluation_runs/{eval_run_uuid}. The run must be in a terminal status (successful, partially_successful, failed, or cancelled). For runs still in progress, either wait for the run to finish or cancel it, then retry the delete once the run reaches a terminal status.

Path Parameters

eval_run_uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

UUID of the model evaluation run to delete. The run must be in a terminal status (successful, partially_successful, failed, or cancelled). For runs still in progress, either wait for the run to finish or cancel it, then retry the delete.

Request: `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}`

cURL

curl -X DELETE \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/model_evaluation_runs/12345678-1234-1234-1234-123456789012"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

error string optional

Example: example string

Error message if deletion failed

status string, one of: DELETE_MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED, DELETE_MODEL_EVALUATION_RUN_STATUS_SUCCESS, DELETE_MODEL_EVALUATION_RUN_STATUS_FAIL optional

Example: DELETE_MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED

Status of delete operation

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "error": "example string",
  "status": "DELETE_MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET Get Download URL for Model Evaluation Run Results

/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}/results/download_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.

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.

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

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`

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 presigned download URL for model evaluation run results (gzip-compressed JSON), send a GET request to /v2/genai/model_evaluation_runs/{eval_run_uuid}/results/download_url.

Path Parameters

eval_run_uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

UUID of the evaluation run.

Request: `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}/results/download_url`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/gen-ai/model_evaluation_runs/123e4567-e89b-12d3-a456-426614174000/results/download_url"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

download_url string optional

Example: example string

The presigned URL to download the gzip-compressed JSON results file (.json.gz).

expires_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

The time the URL expires at.

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "download_url": "example string",
  "expires_at": "2023-01-01T00:00:00Z"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

Model capabilities (inference, reasoning, vectorization, etc.)

context_window string (int64) optional

Example: 12345

Context window (maximum tokens)

created_at string (date-time) optional

Example: 2021-01-01T00:00:00Z

Creation date / time

description string optional

Example: example string

Model description

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: active

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

model_availability string optional

Example: example string

Model availability (serverless, dedicated, etc.)

name string optional

Example: Llama 3.3 Instruct (70B)

Display name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

parent_uuid string optional

Example: "12345678-1234-1234-1234-123456789012"

Unique id of the model, this model is based on

pricing object optional

Pricing per million tokens (aligns with existing ModelPrice pattern)

Show child properties

input_price_per_million number (double) optional

Example: 0.6

output_price_per_million number (double) optional

Example: 0.9

price_per_audio number (double) optional

Example: 0.002

price_per_image number (double) optional

Example: 0.003

Unit-based pricing for non-token models (e.g., Fal AI image/video/audio generation, speech models). At most one of these is typically populated per model. Token-based models (chat, embeddings) leave all of these at 0 and populate input_price_per_million / output_price_per_million instead.

price_per_megapixel number (double) optional

Example: 3e-05

price_per_second number (double) optional

Example: 0.0001

price_per_thousand_characters number (double) optional

Example: 0.015

price_per_video number (double) optional

Example: 0.05

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional

Example: MODEL_PROVIDER_DIGITALOCEAN

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  },
  "models": [
    {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2021-01-01T00:00:00Z",
      "description": "example string",
      "endpoints": [],
      "id": "llama3.3-70b-instruct",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "lifecycle_status": "active",
      "model_availability": "example string",
      "name": "Llama 3.3 Instruct (70B)",
      "parameter_count": 123,
      "parent_uuid": "\"12345678-1234-1234-1234-123456789012\"",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "updated_at": "2021-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "https://example.com/model.zip",
      "uuid": "\"12345678-1234-1234-1234-123456789012\""
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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`

Payload

Content type application/json

{
  "name": "Production Key"
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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}`

Payload

Content type application/json

{
  "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"Production Key\""
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET List Model Catalog

/v2/gen-ai/models/catalog

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.

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.

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

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`

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"

Returns all available models.

Query Parameters

page integer optional

Example: 1

limit integer optional

Example: 1

Request: `/v2/gen-ai/models/catalog`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  "https://api.digitalocean.com/v2/gen-ai/models/catalog"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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 array of object optional

Show child properties

availability array of string optional

Example: ["example string"]

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

context_window string (int64) optional

Example: 128000

Specs (flat)

creator string optional

Example: "Meta"

Model creator/developer (e.g., "Meta", "Anthropic", "OpenAI")

id string optional

Example: "506a3371-88d0-4047-9212-e2079497ac68"

Identity

model_id string optional

Example: "llama3.1-70b-instruct"

Model identifier used for API calls (e.g., "llama3.1-70b-instruct")

name string optional

Example: "Llama 3.1 70B"

parameter_count number (float) optional

Example: 70

pricing object optional

Pricing per million tokens (aligns with existing ModelPrice pattern)

Show child properties

input_price_per_million number (double) optional

Example: 0.6

output_price_per_million number (double) optional

Example: 0.9

price_per_audio number (double) optional

Example: 0.002

price_per_image number (double) optional

Example: 0.003

price_per_megapixel number (double) optional

Example: 3e-05

price_per_second number (double) optional

Example: 0.0001

price_per_thousand_characters number (double) optional

Example: 0.015

price_per_video number (double) optional

Example: 0.05

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional

Example: MODEL_PROVIDER_DIGITALOCEAN

short_description string optional

Example: "Fast, efficient model for general tasks"

type string optional

Example: "text-to-text"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "data": [
    {
      "availability": [
        "example string"
      ],
      "capabilities": [
        "example string"
      ],
      "context_window": "128000",
      "creator": "\"Meta\"",
      "id": "\"506a3371-88d0-4047-9212-e2079497ac68\"",
      "model_id": "\"llama3.1-70b-instruct\"",
      "name": "\"Llama 3.1 70B\"",
      "parameter_count": 70,
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "short_description": "\"Fast, efficient model for general tasks\"",
      "type": "\"text-to-text\""
    }
  ],
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET Get Model Catalog Card

/v2/gen-ai/models/catalog/{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.

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.

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

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`

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"

Returns detailed information for a specific model in the catalog including capabilities, pricing, and code examples.

Path Parameters

id string required

Example: "example string"

Query Parameters

model_id string optional

Example: "example string"

Model identifier used for API calls (e.g., "llama3.1-70b-instruct"). Alternative to UUID lookup.

Request: `/v2/gen-ai/models/catalog/{id}`

cURL

curl -X GET \
  -H "Content-Type: application/json"  \
  "https://api.digitalocean.com/v2/gen-ai/models/catalog/18bc9b8f-73c5-11f0-b074-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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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 object optional

Detail view for GetModelCatalogCard

Show child properties

availability array of string optional

Example: ["example string"]

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

code_snippets object optional

Code examples for using the model

Show child properties

curl string optional

Example: example string

javascript string optional

Example: example string

python string optional

Example: example string

sdk string optional

Example: example string

context_window string (int64) optional

Example: 128000

Specs (same as Entry)

creator string optional

Example: "Meta"

Model creator/developer (e.g., "Meta", "Anthropic", "OpenAI")

description string optional

Example: "Claude Sonnet 4 is Anthropic's most capable model..."

Card-specific

id string optional

Example: "506a3371-88d0-4047-9212-e2079497ac68"

Identity (same as Entry)

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

model_id string optional

Example: "llama3.1-70b-instruct"

Model identifier used for API calls (e.g., "llama3.1-70b-instruct")

name string optional

Example: "Llama 3.1 70B"

parameter_count number (float) optional

Example: 70

pricing object optional

Pricing per million tokens (aligns with existing ModelPrice pattern)

Show child properties

input_price_per_million number (double) optional

Example: 0.6

output_price_per_million number (double) optional

Example: 0.9

price_per_audio number (double) optional

Example: 0.002

price_per_image number (double) optional

Example: 0.003

price_per_megapixel number (double) optional

Example: 3e-05

price_per_second number (double) optional

Example: 0.0001

price_per_thousand_characters number (double) optional

Example: 0.015

price_per_video number (double) optional

Example: 0.05

provider string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional

Example: MODEL_PROVIDER_DIGITALOCEAN

short_description string optional

Example: "Fast, efficient model for general tasks"

type string optional

Example: "text-to-text"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "data": {
    "availability": [
      "example string"
    ],
    "capabilities": [
      "example string"
    ],
    "code_snippets": {
      "curl": "example string",
      "javascript": "example string",
      "python": "example string",
      "sdk": "example string"
    },
    "context_window": "128000",
    "creator": "\"Meta\"",
    "description": "\"Claude Sonnet 4 is Anthropic's most capable model...\"",
    "id": "\"506a3371-88d0-4047-9212-e2079497ac68\"",
    "modalities": {
      "input": [
        "example string"
      ],
      "output": [
        "example string"
      ]
    },
    "model_id": "\"llama3.1-70b-instruct\"",
    "name": "\"Llama 3.1 70B\"",
    "parameter_count": 70,
    "pricing": {
      "input_price_per_million": 0.6,
      "output_price_per_million": 0.9,
      "price_per_audio": 0.002,
      "price_per_image": 0.003,
      "price_per_megapixel": 0.00003,
      "price_per_second": 0.0001,
      "price_per_thousand_characters": 0.015,
      "price_per_video": 0.05
    },
    "provider": "MODEL_PROVIDER_DIGITALOCEAN",
    "short_description": "\"Fast, efficient model for general tasks\"",
    "type": "\"text-to-text\""
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET List Model Routers

/v2/gen-ai/models/routers

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.

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.

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

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`

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 model routers, send a GET request to /v2/gen-ai/models/routers.

Query Parameters

page integer optional

Example: 1

Page number.

per_page integer optional

Example: 1

Items per page.

Request: `/v2/gen-ai/models/routers`

cURL

curl -X GET \
    -H "Content-Type: application/json"  \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    "https://api.digitalocean.com/v2/gen-ai/models/routers?page=1&per_page=20"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

model_routers array of object optional

The model routers

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

Show child properties

custom_task object optional

Task definition embedded in a model router config.

Additional nested properties not shown. Refer to the full API spec for details.

models array of string optional

Example: ["example string"]

Models assigned to the task

selection_policy object optional

Selection policy preference for choosing among assigned models.

Additional nested properties not shown. Refer to the full API spec for details.

task_slug string optional

Example: "summarization"

Task slug

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  },
  "model_routers": [
    {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

POST Create a Model Router

/v2/gen-ai/models/routers

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.

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.

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

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`

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 router, send a POST request to /v2/gen-ai/models/routers.

Request Body: `application/json`

description string optional

Example: "My Model Router Description"

Model router description

fallback_models array of string optional

Example: ["example string"]

Fallback models

name string optional

Example: "My Model Router"

Model router name

policies array of object optional

Router policies

Show child properties

custom_task object optional

Task definition embedded in a model router config.

Show child properties

description string optional

Example: "Summarize long-form text"

Short task description

name string optional

Example: "Custom Summarization"

Task name

models array of string optional

Example: ["example string"]

Models assigned to the task

selection_policy object optional

Selection policy preference for choosing among assigned models.

Show child properties

prefer string optional

Example: "cheapest"

One of: none, cheapest, fastest

task_slug string optional

Example: "summarization"

Task slug

regions array of string optional

Example: ["example string"]

Target regions for the router

Request: `/v2/gen-ai/models/routers`

Payload

Content type application/json

{
  "description": "\"My Model Router Description\"",
  "fallback_models": [
    "example string"
  ],
  "name": "\"My Model Router\"",
  "policies": [
    {
      "models": [
        "example string"
      ],
      "task_slug": "\"summarization\""
    }
  ],
  "regions": [
    "example string"
  ]
}

cURL

curl -X POST \
    -H "Content-Type: application/json"  \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    "https://api.digitalocean.com/v2/gen-ai/models/routers" \
    -d '{
      "name": "My Model Router",
      "description": "Routes chat traffic across multiple models",
      "regions": ["tor1"],
      "fallback_models": ["openai-gpt-5.4", "kimi-k2.5"],
      "policies": [
        {
          "task_slug": "summarization",
          "models": ["openai-gpt-5.4", "kimi-k2.5"],
          "selection_policy": {
            "prefer": "cheapest"
          }
        }
      ]
    }'

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

Show child properties

custom_task object optional

Task definition embedded in a model router config.

Additional nested properties not shown. Refer to the full API spec for details.

models array of string optional

Example: ["example string"]

Models assigned to the task

selection_policy object optional

Selection policy preference for choosing among assigned models.

Additional nested properties not shown. Refer to the full API spec for details.

task_slug string optional

Example: "summarization"

Task slug

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "model_router": {
    "config": {
      "fallback_models": [
        "example string"
      ],
      "policies": []
    },
    "created_at": "2023-01-01T00:00:00Z",
    "description": "example string",
    "name": "example name",
    "regions": [
      "example string"
    ],
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET List Model Router Presets

/v2/gen-ai/models/routers/presets

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.

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.

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

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`

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 model router presets, send a GET request to /v2/gen-ai/models/routers/presets.

Query Parameters

page integer optional

Example: 1

Page number.

per_page integer optional

Example: 1

Items per page.

Request: `/v2/gen-ai/models/routers/presets`

cURL

curl -X GET \
    -H "Content-Type: application/json"  \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    "https://api.digitalocean.com/v2/gen-ai/models/routers/presets?page=1&per_page=20"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

presets array of object optional

The model router presets

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

Show child properties

custom_task object optional

Task definition embedded in a model router config.

Additional nested properties not shown. Refer to the full API spec for details.

models array of string optional

Example: ["example string"]

Models assigned to the task

selection_policy object optional

Selection policy preference for choosing among assigned models.

Additional nested properties not shown. Refer to the full API spec for details.

task_slug string optional

Example: "summarization"

Task slug

display_name string optional

Example: example name

Display name for UI surfaces

long_description string optional

Example: example string

Long description for details views

short_description string optional

Example: example string

Short description for list views

slug string optional

Example: example string

Stable slug for routing usage

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  },
  "presets": [
    {
      "display_name": "example name",
      "long_description": "example string",
      "short_description": "example string",
      "slug": "example string"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET List Model Router Task Presets

/v2/gen-ai/models/routers/tasks/presets

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.

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.

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

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`

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 model router task presets, send a GET request to /v2/gen-ai/models/routers/tasks/presets.

Query Parameters

page integer optional

Example: 1

Page number.

per_page integer optional

Example: 1

Items per page.

Request: `/v2/gen-ai/models/routers/tasks/presets`

cURL

curl -X GET \
    -H "Content-Type: application/json"  \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    "https://api.digitalocean.com/v2/gen-ai/models/routers/tasks/presets?page=1&per_page=20"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

previous string optional

Example: example string

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

tasks array of object optional

The task presets

Show child properties

category string optional

Example: example string

Higher-level grouping used by the UI

description string optional

Example: example string

Task description

models array of string optional

Example: ["example string"]

Default models assigned to this task

name string optional

Example: example name

Display name

selection_policy object optional

Selection policy preference for choosing among assigned models.

Show child properties

prefer string optional

Example: "cheapest"

One of: none, cheapest, fastest

tags array of string optional

Example: ["example string"]

Lightweight labels for filtering

task_slug string optional

Example: example string

Task slug

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  },
  "tasks": [
    {
      "category": "example string",
      "description": "example string",
      "models": [
        "example string"
      ],
      "name": "example name",
      "tags": [
        "example string"
      ],
      "task_slug": "example string"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an Existing Model Router

/v2/gen-ai/models/routers/{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.

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.

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

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`

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 model router, send a GET request to /v2/gen-ai/models/routers/{uuid}.

Path Parameters

uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

Model router id

Request: `/v2/gen-ai/models/routers/{uuid}`

cURL

curl -X GET \
    -H "Content-Type: application/json"  \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    "https://api.digitalocean.com/v2/gen-ai/models/routers/12345678-1234-1234-1234-123456789012"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

Show child properties

custom_task object optional

Task definition embedded in a model router config.

Additional nested properties not shown. Refer to the full API spec for details.

models array of string optional

Example: ["example string"]

Models assigned to the task

selection_policy object optional

Selection policy preference for choosing among assigned models.

Additional nested properties not shown. Refer to the full API spec for details.

task_slug string optional

Example: "summarization"

Task slug

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "model_router": {
    "config": {
      "fallback_models": [
        "example string"
      ],
      "policies": []
    },
    "created_at": "2023-01-01T00:00:00Z",
    "description": "example string",
    "name": "example name",
    "regions": [
      "example string"
    ],
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

PUT Update a Model Router

/v2/gen-ai/models/routers/{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.

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.

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

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`

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 router, send a PUT request to /v2/gen-ai/models/routers/{uuid}.

Path Parameters

uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

Model router id

Request Body: `application/json`

description string optional

Example: "My Model Router Description"

Model router description

fallback_models array of object optional

name string optional

Example: "My Model Router"

Model router name

policies array of object optional

Router policies

Show child properties

custom_task object optional

Task definition embedded in a model router config.

Show child properties

description string optional

Example: "Summarize long-form text"

Short task description

name string optional

Example: "Custom Summarization"

Task name

models array of string optional

Example: ["example string"]

Models assigned to the task

selection_policy object optional

Selection policy preference for choosing among assigned models.

Show child properties

prefer string optional

Example: "cheapest"

One of: none, cheapest, fastest

task_slug string optional

Example: "summarization"

Task slug

regions array of string optional

Example: ["example string"]

Target regions for the router

uuid string optional

Example: "12345678-1234-1234-1234-123456789012"

Model router id

Request: `/v2/gen-ai/models/routers/{uuid}`

Payload

Content type application/json

{
  "description": "\"My Model Router Description\"",
  "fallback_models": [],
  "name": "\"My Model Router\"",
  "policies": [
    {
      "models": [
        "example string"
      ],
      "task_slug": "\"summarization\""
    }
  ],
  "regions": [
    "example string"
  ],
  "uuid": "\"12345678-1234-1234-1234-123456789012\""
}

cURL

curl -X PUT \
    -H "Content-Type: application/json"  \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    "https://api.digitalocean.com/v2/gen-ai/models/routers/12345678-1234-1234-1234-123456789012" \
    -d '{
      "name": "My Model Router",
      "description": "Updated router description",
      "regions": ["tor1"],
      "fallback_models": ["openai-gpt-5.4", "kimi-k2.5"],
      "policies": [
        {
          "task_slug": "summarization",
          "models": ["openai-gpt-5.4"],
          "selection_policy": {
            "prefer": "cheapest"
          }
        }
      ]
    }'

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

Show child properties

custom_task object optional

Task definition embedded in a model router config.

Additional nested properties not shown. Refer to the full API spec for details.

models array of string optional

Example: ["example string"]

Models assigned to the task

selection_policy object optional

Selection policy preference for choosing among assigned models.

Additional nested properties not shown. Refer to the full API spec for details.

task_slug string optional

Example: "summarization"

Task slug

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "model_router": {
    "config": {
      "fallback_models": [
        "example string"
      ],
      "policies": []
    },
    "created_at": "2023-01-01T00:00:00Z",
    "description": "example string",
    "name": "example name",
    "regions": [
      "example string"
    ],
    "updated_at": "2023-01-01T00:00:00Z",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a Model Router

/v2/gen-ai/models/routers/{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.

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.

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

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`

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 model router, send a DELETE request to /v2/gen-ai/models/routers/{uuid}.

Path Parameters

uuid string required

Example: "123e4567-e89b-12d3-a456-426614174000"

Model router id

Request: `/v2/gen-ai/models/routers/{uuid}`

cURL

curl -X DELETE \
    -H "Content-Type: application/json"  \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    "https://api.digitalocean.com/v2/gen-ai/models/routers/12345678-1234-1234-1234-123456789012"

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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 model router

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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`

Payload

Content type application/json

{
  "code": "example string",
  "redirect_url": "example string"
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "refresh_token": "example string",
  "token": "example string"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "url": "example string"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

previous string optional

Example: example string

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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`

Payload

Content type application/json

{
  "api_key": "\"sk-proj--123456789098765432123456789\"",
  "name": "\"Production Key\""
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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}`

Payload

Content type application/json

{
  "api_key": "\"sk-ant-12345678901234567890123456789012\"",
  "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"Production Key\""
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

previous string optional

Example: example string

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
      "mcp_servers": [],
      "name": "example name",
      "parent_agents": [],
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "provide_citations": true,
      "reasoning_effort": "example string",
      "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,
      "thinking_token_budget": 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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "regions": [
    {
      "inference_url": "example string",
      "region": "example string",
      "serves_batch": true,
      "serves_inference": true,
      "stream_inference_url": "example string"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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`

Payload

Content type application/json

{
  "days": [
    123
  ],
  "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "time": "example string"
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

Additional nested properties not shown. Refer to the full API spec for details.

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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_type string, one of: EVALUATION_DATASET_TYPE_UNKNOWN, EVALUATION_DATASET_TYPE_ADK, EVALUATION_DATASET_TYPE_NON_ADK, EVALUATION_DATASET_TYPE_MODEL optional

Example: EVALUATION_DATASET_TYPE_UNKNOWN

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

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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`

Payload

Content type application/json

{
  "agent_uuids": [
    "example string"
  ],
  "description": "example string",
  "name": "example name"
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

Additional nested properties not shown. Refer to the full API spec for details.

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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_type string, one of: EVALUATION_DATASET_TYPE_UNKNOWN, EVALUATION_DATASET_TYPE_ADK, EVALUATION_DATASET_TYPE_NON_ADK, EVALUATION_DATASET_TYPE_MODEL optional

Example: EVALUATION_DATASET_TYPE_UNKNOWN

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

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

Additional nested properties not shown. Refer to the full API spec for details.

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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_type string, one of: EVALUATION_DATASET_TYPE_UNKNOWN, EVALUATION_DATASET_TYPE_ADK, EVALUATION_DATASET_TYPE_NON_ADK, EVALUATION_DATASET_TYPE_MODEL optional

Example: EVALUATION_DATASET_TYPE_UNKNOWN

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

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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}`

Payload

Content type application/json

{
  "description": "example string",
  "name": "example name",
  "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

Additional nested properties not shown. Refer to the full API spec for details.

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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_type string, one of: EVALUATION_DATASET_TYPE_UNKNOWN, EVALUATION_DATASET_TYPE_ADK, EVALUATION_DATASET_TYPE_NON_ADK, EVALUATION_DATASET_TYPE_MODEL optional

Example: EVALUATION_DATASET_TYPE_UNKNOWN

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

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Show child properties

enabled boolean optional

Example: true

Whether reranking is enabled for retrieval

model string optional

Example: "bge-reranker-v2-m3"

Reranker model internal name

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Show child properties

capabilities array of string optional

Example: ["example string"]

Capabilities supported by this endpoint (e.g. input_text, output_text, input_image)

endpoint string optional

Example: /chat/responses

The endpoint path (e.g. /chat/responses)

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

modalities object optional

Input/output modalities

Show child properties

input array of string optional

Example: ["example string"]

output array of string optional

Example: ["example string"]

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Show child properties

default_string string optional

Example: example string

String default value (for type="dropdown", e.g. "medium")

default_value number (double) optional

Example: 0.7

Numeric default value (for type="number")

max number (double) optional

Example: 1

Maximum allowed value (for type="number")

min number (double) optional

Example: 0

Minimum allowed value (for type="number")

name string optional

Example: temperature

Setting key name (e.g. "max_tokens", "temperature", "resolution")

options array of string optional

Example: ["example string"]

Allowed values for dropdown selections (for type="dropdown")

step number (double) optional

Example: 123

Step increment for numeric settings (for type="number")

type string optional

Example: number

Setting value type: "number" or "dropdown"

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

Show child properties

fallback_models array of string optional

Example: ["example string"]

Router-level fallback models

policies array of object optional

Task routing policies

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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

previous string optional

Example: example string

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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,
      "mcp_servers": [],
      "name": "example name",
      "parent_agents": [],
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "provide_citations": true,
      "reasoning_effort": "example string",
      "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,
      "thinking_token_budget": 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
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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`

Payload

Content type application/json

{
  "agent_uuids": [
    "example string"
  ],
  "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

cURL

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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

reranking_config object optional

Configuration for cross-encoder reranking during retrieval.

Additional nested properties not shown. Refer to the full API spec for details.

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

mcp_servers array of object optional

MCP (Model Context Protocol) servers attached to this agent

Show child properties

allowed_tools array of string optional

Example: ["example string"]

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

Additional nested properties not shown. Refer to the full API spec for details.

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

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.

benchmark_score object optional

Benchmark scores for this model, stored as arbitrary JSON

Additional nested properties not shown. Refer to the full API spec for details.

capabilities array of string optional

Example: ["example string"]

High-level capabilities (e.g. tool_calling, vision, streaming)

context_window string (int64) optional

Example: 12345

Context window size in tokens

created_at string (date-time) optional

Example: 2023-01-01T00:00:00Z

Creation date / time

endpoints array of object optional

Available endpoints and their capabilities

Additional nested properties not shown. Refer to the full API spec for details.

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

lifecycle_status string optional

Example: example string

Lifecycle status of the model (internal, public-preview, active, deprecated, end_of_life)

metadata object optional

Additional meta data

Additional nested properties not shown. Refer to the full API spec for details.

modalities object optional

Input/output modalities

Additional nested properties not shown. Refer to the full API spec for details.

name string optional

Example: example name

Name of the model

parameter_count number (float) optional

Example: 123

Parameter count in billions

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

reasoning_efforts array of string optional

Example: ["example string"]

Available reasoning efforts for this model

settings array of object optional

Playground settings derived from model metadata

Additional nested properties not shown. Refer to the full API spec for details.

thinking boolean optional

Example: true

Whether this model supports extended thinking (Anthropic models)

type string optional

Example: example string

Model type (chat, embedding, image, reasoning, coding)

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

model_router object optional

Model router

Show child properties

config object optional

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

description string optional

Example: example string

Description

name string optional

Example: example name

Name of the model router

regions array of string optional

Example: ["example string"]

Target regions for the router

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

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

reasoning_effort string optional

Example: example string

The reasoning effort for the agent

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

thinking_token_budget integer (int64) optional

Example: 123

The thinking token budget for Anthropic extended thinking (0 = disabled)

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_type string, one of: EVALUATION_DATASET_TYPE_UNKNOWN, EVALUATION_DATASET_TYPE_ADK, EVALUATION_DATASET_TYPE_NON_ADK, EVALUATION_DATASET_TYPE_MODEL optional

Example: EVALUATION_DATASET_TYPE_UNKNOWN

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

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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"
  }
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "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.

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.

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

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`

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

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given 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_type string, one of: EVALUATION_DATASET_TYPE_UNKNOWN, EVALUATION_DATASET_TYPE_ADK, EVALUATION_DATASET_TYPE_NON_ADK, EVALUATION_DATASET_TYPE_MODEL optional

Example: EVALUATION_DATASET_TYPE_UNKNOWN

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

evaluation_scope string, one of: EVALUATION_SCOPE_UNSPECIFIED, EVALUATION_SCOPE_AGENT, EVALUATION_SCOPE_MODEL optional

Example: EVALUATION_SCOPE_UNSPECIFIED

Scope that determines whether a metric belongs to agent evaluation or model evaluation. For backwards compatibility, UNSPECIFIED defaults to agent metrics only in list operations.

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, METRIC_TYPE_MODEL_QUALITY, METRIC_TYPE_MODEL_SAFETY 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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json

id string required

Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required

Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional

Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

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

200

{
  "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
    }
  ]
}

401

{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

404

{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

429

{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}

500

{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

default

{
  "id": "example_error",
  "message": "some error message"
}

GradientAI Platform

Endpoints

GET List Agents

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Query Parameters

Request: /v2/gen-ai/agents

Responses

Response

POST Create an Agent

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Request Body: application/json

Request: /v2/gen-ai/agents

Responses

Response

GET List Agent API Keys

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Query Parameters

Request: /v2/gen-ai/agents/{agent_uuid}/api_keys

Responses

Response

POST Create an Agent API Key

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/gen-ai/agents/{agent_uuid}/api_keys

Responses

Response

PUT Update API Key for an Agent

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}

Responses

Response

DELETE Delete API Key for an Agent

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request: /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}

Responses

Response

PUT Regenerate API Key for an Agent

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request: /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate

Responses

Response

POST Add Function Route to an Agent

OAuth Authentication

Scopes

How to Authenticate with OAuth

Authenticate with a Bearer Authorization Header

Path Parameters

Request Body: application/json

Request: /v2/gen-ai/agents/{agent_uuid}/functions

Responses

Response

PUT Update Function Route for an Agent

OAuth Authentication

Request: `/v2/gen-ai/agents`

Request Body: `application/json`

Request: `/v2/gen-ai/agents`

Request: `/v2/gen-ai/agents/{agent_uuid}/api_keys`

Request Body: `application/json`

Request: `/v2/gen-ai/agents/{agent_uuid}/api_keys`

Request Body: `application/json`

Request: `/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}`

Request: `/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}`

Request: `/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate`

Request Body: `application/json`

Request: `/v2/gen-ai/agents/{agent_uuid}/functions`

Request Body: `application/json`

Request: `/v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}`

Request: `/v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}`

Request Body: `application/json`

Request: `/v2/gen-ai/agents/{agent_uuid}/guardrails`

Request: `/v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}`

Request: `/v2/gen-ai/agents/{agent_uuid}/knowledge_bases`

Request: `/v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}`

Request: `/v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}`

Request Body: `application/json`