--- title: Agent Platform API product: Inference url: https://docs.digitalocean.com/reference/api/reference/agent-platform-api/ --- > **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document). # Agent Platform API [View full API reference](https://docs.digitalocean.com/reference/api/reference/index.html.md) 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](#genai_list_agents) - **POST** [Create an Agent](#genai_create_agent) - **GET** [List Agent API Keys](#genai_list_agent_api_keys) - **POST** [Create an Agent API Key](#genai_create_agent_api_key) - **PUT** [Update API Key for an Agent](#genai_update_agent_api_key) - **DELETE** [Delete API Key for an Agent](#genai_delete_agent_api_key) - **PUT** [Regenerate API Key for an Agent](#genai_regenerate_agent_api_key) - **POST** [Add Function Route to an Agent](#genai_attach_agent_function) - **PUT** [Update Function Route for an Agent](#genai_update_agent_function) - **DELETE** [Delete Function Route for an Agent](#genai_detach_agent_function) - **POST** [Attach Guardrails to an Agent](#genai_attach_agent_guardrails) - **DELETE** [Detach a Guardrail from an Agent](#genai_detach_agent_guardrail) - **POST** [Attach Knowledge Bases to an Agent](#genai_attach_knowledge_bases) - **POST** [Attach Knowledge Base to an Agent](#genai_attach_knowledge_base) - **DELETE** [Detach Knowledge Base from an Agent](#genai_detach_knowledge_base) - **POST** [Add Agent Route to an Agent](#genai_attach_agent) - **PUT** [Update Agent Route for an Agent](#genai_update_attached_agent) - **DELETE** [Delete Agent Route for an Agent](#genai_detach_agent) - **GET** [Retrieve an Existing Agent](#genai_get_agent) - **PUT** [Update an Agent](#genai_update_agent) - **DELETE** [Delete an Agent](#genai_delete_agent) - **GET** [View Agent Routes](#genai_get_agent_children) - **PUT** [Update Agent Status](#genai_update_agent_deployment_visibility) - **GET** [Get Agent Usage](#genai_get_agent_usage) - **GET** [List Agent Versions](#genai_list_agent_versions) - **PUT** [Rollback to Agent Version](#genai_rollback_to_agent_version) - **GET** [List Anthropic API Keys](#genai_list_anthropic_api_keys) - **POST** [Create Anthropic API Key](#genai_create_anthropic_api_key) - **GET** [Get Anthropic API Key](#genai_get_anthropic_api_key) - **PUT** [Update Anthropic API Key](#genai_update_anthropic_api_key) - **DELETE** [Delete Anthropic API Key](#genai_delete_anthropic_api_key) - **GET** [List agents by Anthropic key](#genai_list_agents_by_anthropic_key) - **GET** [List Custom Models](#genai_list_custom_models) - **POST** [Import Custom Model](#genai_import_custom_model) - **GET** [Get Custom Model](#genai_get_custom_model) - **DELETE** [Delete Custom Model](#genai_delete_custom_model) - **PATCH** [Update Custom Model Metadata](#genai_update_custom_model_metadata) - **GET** [List Evaluation Datasets](#genai_list_evaluation_datasets) - **POST** [Create Evaluation Dataset](#genai_create_evaluation_dataset) - **POST** [Create Presigned URLs for Evaluation Dataset File Upload](#genai_create_evaluation_dataset_file_upload_presigned_urls) - **DELETE** [Delete Evaluation Dataset](#genai_delete_evaluation_dataset) - **GET** [Get Download URL for Evaluation Dataset](#genai_get_evaluation_dataset_download_url) - **GET** [List Evaluation Metrics](#genai_list_evaluation_metrics) - **POST** [Create Custom Evaluation Metric](#genai_create_custom_evaluation_metric) - **PUT** [Update Custom Evaluation Metric](#genai_update_custom_evaluation_metric) - **DELETE** [Delete Custom Evaluation Metric](#genai_delete_custom_evaluation_metric) - **POST** [Run an Evaluation Test Case](#genai_run_evaluation_test_case) - **GET** [Retrieve Information About an Existing Evaluation Run](#genai_get_evaluation_run) - **GET** [Retrieve Results of an Evaluation Run](#genai_get_evaluation_run_results) - **GET** [Retrieve Results of an Evaluation Run Prompt](#genai_get_evaluation_run_prompt_results) - **GET** [List Evaluation Test Cases](#genai_list_evaluation_test_cases) - **POST** [Create Evaluation Test Case.](#genai_create_evaluation_test_case) - **GET** [List Evaluation Runs by Test Case](#genai_list_evaluation_runs_by_test_case) - **GET** [Retrieve Information About an Existing Evaluation Test Case](#genai_get_evaluation_test_case) - **PUT** [Update an Evaluation Test Case.](#genai_update_evaluation_test_case) - **GET** [List Indexing Jobs for a Knowledge Base](#genai_list_indexing_jobs) - **POST** [Start Indexing Job for a Knowledge Base](#genai_create_indexing_job) - **GET** [List Data Sources for Indexing Job for a Knowledge Base](#genai_list_indexing_job_data_sources) - **GET** [Get Signed URL for Indexing Job Details](#genai_get_indexing_job_details_signed_url) - **GET** [Retrieve Status of Indexing Job for a Knowledge Base](#genai_get_indexing_job) - **PUT** [Cancel Indexing Job for a Knowledge Base](#genai_cancel_indexing_job) - **GET** [List Knowledge Bases](#genai_list_knowledge_bases) - **POST** [Create a Knowledge Base](#genai_create_knowledge_base) - **POST** [Create Presigned URLs for Data Source File Upload](#genai_create_data_source_file_upload_presigned_urls) - **GET** [List Data Sources for a Knowledge Base](#genai_list_knowledge_base_data_sources) - **POST** [Add Data Source to a Knowledge Base](#genai_create_knowledge_base_data_source) - **PUT** [Update Data Source options](#genai_update_knowledge_base_data_source) - **DELETE** [Delete a Data Source from a Knowledge Base](#genai_delete_knowledge_base_data_source) - **GET** [List Indexing Jobs for a Knowledge Base](#genai_list_indexing_jobs_by_knowledge_base) - **GET** [Retrieve Information About an Existing Knowledge Base](#genai_get_knowledge_base) - **PUT** [Update a Knowledge Base](#genai_update_knowledge_base) - **DELETE** [Delete a Knowledge Base](#genai_delete_knowledge_base) - **POST** [Create Presigned URLs for Model Evaluation Dataset File Upload](#genai_create_model_eval_dataset_upload_presigned_urls) - **GET** [List Model Evaluation Metrics](#genai_list_model_evaluation_metrics) - **GET** [List Model Evaluation Presets](#genai_list_model_evaluation_presets) - **GET** [Retrieve Model Evaluation Preset](#genai_get_model_evaluation_preset) - **DELETE** [Delete Model Evaluation Preset](#genai_delete_model_evaluation_preset) - **GET** [List Model Evaluation Runs](#genai_list_model_evaluation_runs) - **POST** [Create Model Evaluation Run](#genai_create_model_evaluation_run) - **GET** [Retrieve Model Evaluation Run](#genai_get_model_evaluation_run) - **PATCH** [Update Model Evaluation Run](#genai_update_model_evaluation_run) - **DELETE** [Delete Model Evaluation Run](#genai_delete_model_evaluation_run) - **PUT** [Cancel Model Evaluation Run](#genai_cancel_model_evaluation_run) - **GET** [Get Download URL for Model Evaluation Run Results](#genai_get_model_evaluation_run_results_download_url) - **GET** [List Available Models](#genai_list_models) - **GET** [List Model API Keys](#genai_list_model_api_keys) - **POST** [Create a Model API Key](#genai_create_model_api_key) - **PUT** [Update API Key for a Model](#genai_update_model_api_key) - **DELETE** [Delete API Key for a Model](#genai_delete_model_api_key) - **PUT** [Regenerate API Key for a Model](#genai_regenerate_model_api_key) - **GET** [List Model Catalog](#genai_list_model_catalog) - **GET** [Get Model Catalog Card](#genai_get_model_catalog_card) - **GET** [List Model Routers](#genai_list_model_routers) - **POST** [Create a Model Router](#genai_create_model_router) - **GET** [List Model Router Presets](#genai_list_model_router_presets) - **GET** [List Model Router Task Presets](#genai_list_model_router_task_presets) - **GET** [Retrieve an Existing Model Router](#genai_get_model_router) - **PUT** [Update a Model Router](#genai_update_model_router) - **DELETE** [Delete a Model Router](#genai_delete_model_router) - **POST** [Get Oauth2 Dropbox Tokens](#genai_create_oauth2_dropbox_tokens) - **GET** [Get Oauth2 URL](#genai_get_oauth2_url) - **GET** [List OpenAI API Keys](#genai_list_openai_api_keys) - **POST** [Create OpenAI API Key](#genai_create_openai_api_key) - **GET** [Get OpenAI API Key](#genai_get_openai_api_key) - **PUT** [Update OpenAI API Key](#genai_update_openai_api_key) - **DELETE** [Delete OpenAI API Key](#genai_delete_openai_api_key) - **GET** [List agents by OpenAI key](#genai_list_agents_by_openai_key) - **GET** [List Datacenter Regions](#genai_list_datacenter_regions) - **GET** [List Common Scenario & Goal Library](#genai_list_scenario_library) - **POST** [Create Scenario Set From Library](#genai_create_scenario_set_from_library) - **GET** [List Scenarios In Library Entry](#genai_list_scenario_library_scenarios) - **GET** [List Scenario Sets](#genai_list_scenario_sets) - **POST** [Create Scenario Set](#genai_create_scenario_set) - **POST** [Create Presigned URLs for Scenario Set File Upload](#genai_create_scenario_set_upload_presigned_urls) - **POST** [Generate Scenario Set](#genai_create_generated_scenario_set) - **GET** [Retrieve Scenario Set](#genai_get_scenario_set) - **PUT** [Update Scenario Set](#genai_update_scenario_set) - **DELETE** [Delete Scenario Set](#genai_delete_scenario_set) - **GET** [Retrieve Scenario Set Download URL](#genai_get_scenario_set_download_url) - **POST** [Duplicate Scenario Set](#genai_create_duplicate_scenario_set) - **GET** [List Scenarios](#genai_list_scenarios) - **POST** [Create scheduled indexing for knowledge base](#genai_create_scheduled_indexing) - **GET** [Get Scheduled Indexing for Knowledge Base](#genai_get_scheduled_indexing) - **DELETE** [Delete Scheduled Indexing](#genai_delete_scheduled_indexing) - **GET** [List Simulation Runs](#genai_list_simulation_runs) - **POST** [Create Simulation Run](#genai_create_simulation_run) - **GET** [Retrieve Simulation Run](#genai_get_simulation_run) - **PUT** [Update Simulation Run](#genai_update_simulation_run) - **DELETE** [Delete Simulation Run](#genai_delete_simulation_run) - **PATCH** [Cancel Simulation Run](#genai_patch_cancel_simulation_run) - **GET** [List Simulation Journeys](#genai_list_simulation_journeys) - **GET** [Retrieve Simulation Journey](#genai_get_simulation_journey) - **GET** [Retrieve Journey Trajectory](#genai_get_simulation_journey_trajectory) - **GET** [Retrieve Journey Trajectory Download URL](#genai_get_simulation_journey_trajectory_url) - **GET** [List Workspaces](#genai_list_workspaces) - **POST** [Create a Workspace](#genai_create_workspace) - **GET** [Retrieve an Existing Workspace](#genai_get_workspace) - **PUT** [Update a Workspace](#genai_update_workspace) - **DELETE** [Delete a Workspace](#genai_delete_workspace) - **GET** [List agents by Workspace](#genai_list_agents_by_workspace) - **PUT** [Move Agents to a Workspace](#genai_update_agents_workspace) - **GET** [List Evaluation Test Cases by Workspace](#genai_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](https://cloud.digitalocean.com/account/api/tokens) 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](https://docs.digitalocean.com/reference/api/oauth-api/index.html.md) - `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 | `:read` | | POST | Create | `:create` | | PUT/PATCH | Update | `:update` | | DELETE | Delete | `: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 ```bash 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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 `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool to retrieve content from public web pages. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool to search the public web for current information. `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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", "web_fetch_enabled": true, "web_search_enabled": true } ], "links": { "pages": { "first": "example string", "last": "example string", "next": "example string", "previous": "example string" } }, "meta": { "page": 123, "pages": 123, "total": 123 } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create an Agent `/v2/gen-ai/agents` 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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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` `web_fetch_enabled` boolean optional Example: `true` Whether the agent can use the built-in web_fetch tool to retrieve content from public web pages. `web_search_enabled` boolean optional Example: `true` Whether the agent can use the built-in web_search tool to search the public web for current information. `workspace_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier for the workspace ##### Request: `/v2/gen-ai/agents` ### Payload Content type `application/json` ```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, "web_fetch_enabled": true, "web_search_enabled": true, "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents" \ -d '{ "name": "api-create", "model_uuid": "95ea6652-75ed-11ef-bf8f-4e013e2ddde4", "instruction": "be a weather reporter", "description": "weather-agent", "project_id": "37455431-84bd-4fa2-94cf-e8486f8f8c5e", "tags": [ "tag1" ], "region": "tor1", "knowledge_base_uuid": [ "9758a232-b351-11ef-bf8f-4e013e2ddde4" ] }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Agent API Keys `/v2/gen-ai/agents/{agent_uuid}/api_keys` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/api_keys" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_infos` array of object optional Api key infos **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date `created_by` string (uint64) optional Example: `12345` Created by `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted date `name` string optional Example: `example name` Name `secret_key` string optional Example: `example string` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create an Agent API Key `/v2/gen-ai/agents/{agent_uuid}/api_keys` 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` ```json { "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"", "name": "Production Key" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys" \ -d '{ "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "name": "test-key" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Agent API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date `created_by` string (uint64) optional Example: `12345` Created by `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted date `name` string optional Example: `example name` Name `secret_key` string optional Example: `example string` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` 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` ```json { "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"", "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"", "name": "\"Production Key\"" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \ -d '{ "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4", "name": "test-key2" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Agent API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date `created_by` string (uint64) optional Example: `12345` Created by `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted date `name` string optional Example: `example name` Name `secret_key` string optional Example: `example string` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Agent API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date `created_by` string (uint64) optional Example: `12345` Created by `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted date `name` string optional Example: `example name` Name `secret_key` string optional Example: `example string` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` 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 ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys/11efcf7e-824d-2808-bf8f-4e013e2ddde4/regenerate" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Agent API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date `created_by` string (uint64) optional Example: `12345` Created by `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted date `name` string optional Example: `example name` Name `secret_key` string optional Example: `example string` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Add Function Route to an Agent `/v2/gen-ai/agents/{agent_uuid}/functions` 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` ```json { "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"", "description": "\"My Function Description\"", "faas_name": "\"my-function\"", "faas_namespace": "\"default\"", "function_name": "\"My Function\"" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/functions" \ -d '{ "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "function_name": "funzip", "description": "Use when you need the zipcode for a city", "input_schema": { "city": { "description": "the city you want a zipcode for", "required": true, "type": "string" } }, "output_schema": { "zip_code": { "description": "The zipcode of the desired city", "type": "number" } }, "faas_namespace": "fn-2014dc98-faa1-45f4-ba1f-59910cb3d399", "faas_name": "default/get-zipcode" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Function Route for an Agent `/v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}` 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` ```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 ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/functions/b00e74f6-985c-11ef-bf8f-4e013e2ddde4" \ -d '{ "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "function_uuid": "6cc5cda5-9ac3-11ef-bf8f-4e013e2ddde4", "function_name": "func-rename" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Function Route for an Agent `/v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/ff47f5b7-96e5-11ef-bf8f-4e013e2ddde4/functions/6cc5cda5-9ac3-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Attach Guardrails to an Agent `/v2/gen-ai/agents/{agent_uuid}/guardrails` 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` ```json { "agent_uuid": "\"12345678-1234-1234-1234-123456789012\"", "guardrails": [ { "guardrail_uuid": "123e4567-e89b-12d3-a456-426614174000", "priority": 123 } ] } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1c8be326-00fe-11f1-b542-ca68c578b05c/guardrails" \ -d '{ "guardrails": [ { "guardrail_uuid": "69bcc61c-2bb2-49fd-b6ed-7c1bd73d6442", "priority": 1 }, { "guardrail_uuid": "dc72b12b-bd45-46c9-bca1-00a6624aac3a", "priority": 2 } ] }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Detach a Guardrail from an Agent `/v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1c8be326-00fe-11f1-b542-ca68c578b04c/guardrails/69bcc61c-2bb2-49fd-b6ed-7c1bd73d6572" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Attach Knowledge Bases to an Agent `/v2/gen-ai/agents/{agent_uuid}/knowledge_bases` 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 ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/knowledge_bases" \ -d '{ "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "knowledge_base_uuids": [ "9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4", "683c3100-7c18-4c94-aea4-5ac5875cc87c", "4887a78b-74af-46b3-98f4-451a48f9cc5e" ] }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` 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 ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/knowledge_bases/9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4" \ -d '{ "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "agent_uuid": "9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4/data_sources/bd2a2db5-b8b0-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` 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` ```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 ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/child_agents/6a09d603-b68d-11ef-bf8f-4e013e2ddde4" \ -d '{ "parent_agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "child_agent_uuid": "6a09d603-b68d-11ef-bf8f-4e013e2ddde4", "route_name": "route-token-stat", "if_case": "for any token related statistics, use this route" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `child_agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Routed agent id `parent_agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` A unique identifier for the parent agent. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "child_agent_uuid": "123e4567-e89b-12d3-a456-426614174000", "parent_agent_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` 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` ```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 ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/child_agents/18c4c90c-cc40-11ef-bf8f-4e013e2ddde4" \ -d '{ "parent_agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "child_agent_uuid": "18c4c90c-cc40-11ef-bf8f-4e013e2ddde4", "route_name": "route-rename-api", "if_case": "if any token related statistics, use this route only", "uuid":"a22d2004-bbaa-11ef-bf8f-4e013e2ddde4" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `child_agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Routed agent id `parent_agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` A unique identifier for the parent agent. `rollback` boolean optional Example: `true` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id of linkage **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/ff47f5b7-96e5-11ef-bf8f-4e013e2ddde4/child_agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `child_agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Routed agent id `parent_agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Pagent agent id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "child_agent_uuid": "123e4567-e89b-12d3-a456-426614174000", "parent_agent_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve an Existing Agent `/v2/gen-ai/agents/{uuid}` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update an Agent `/v2/gen-ai/agents/{uuid}` 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](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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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` Defines the cumulative probability threshold for word selection, specified as a number between 0 and 1. Higher values allow for more diverse outputs, while lower values ensure focused and coherent responses. `uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique agent id `web_fetch_enabled` boolean optional Example: `true` Optional. Set to true to let the agent use the built-in web_fetch tool to retrieve content from public web pages, or false to disable it. `web_search_enabled` boolean optional Example: `true` Optional. Set to true to let the agent use the built-in web_search tool to search the public web for current information, or false to disable it. ##### Request: `/v2/gen-ai/agents/{uuid}` ### Payload Content type `application/json` ```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\"", "web_fetch_enabled": true, "web_search_enabled": true } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4" \ -d '{ "uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "name": "rename-agent-api", "instruction": "be a weather reporter and act like you are a pro", "description": "weather-agent2", "model_uuid": "95ea6652-75ed-11ef-bf8f-4e013e2ddde4", "project_id": "37455431-84bd-4fa2-94cf-e8486f8f8c5e", "tags": [ "tag2" ], "k": 5, "temperature": 1, "top_p": 1, "max_tokens": 250 }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete an Agent `/v2/gen-ai/agents/{uuid}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agent/5581a586-a745-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET View Agent Routes `/v2/gen-ai/agents/{uuid}/child_agents` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/child_agents" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Agent Status `/v2/gen-ai/agents/{uuid}/deployment_visibility` 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` ```json { "uuid": "\"12345678-1234-1234-1234-123456789012\"", "visibility": "VISIBILITY_UNKNOWN" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/deployment_visibility" \ -d '{ "uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "visibility": "VISIBILITY_PUBLIC" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true, "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get Agent Usage `/v2/gen-ai/agents/{uuid}/usage` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/genai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/usage?start=2024-01-01T00:00:00Z&stop=2024-01-31T23:59:59Z" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `log_insights_usage` object optional Resource Usage Description **Show child properties** `measurements` array of object optional **Show child properties** `tokens` integer (int64) optional Example: `123` `usage_type` string optional Example: `example string` `resource_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `start` string (date-time) optional Example: `2023-01-01T00:00:00Z` `stop` string (date-time) optional Example: `2023-01-01T00:00:00Z` `usage` object optional Resource Usage Description **Show child properties** `measurements` array of object optional **Show child properties** `tokens` integer (int64) optional Example: `123` `usage_type` string optional Example: `example string` `resource_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `start` string (date-time) optional Example: `2023-01-01T00:00:00Z` `stop` string (date-time) optional Example: `2023-01-01T00:00:00Z` **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Agent Versions `/v2/gen-ai/agents/{uuid}/versions` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/versions" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `example@example.com` User who created this version `currently_applied` boolean optional Example: `true` Whether this is the currently applied configuration `description` string optional Example: `example string` Description of the agent `id` string (uint64) optional Example: `12345` Unique identifier `instruction` string optional Example: `example string` Instruction for the agent `k` integer (int64) optional Example: `123` K value for the agent's configuration `max_tokens` integer (int64) optional Example: `123` Max tokens setting for the agent `model_name` string optional Example: `example name` Name of model associated to the agent version `name` string optional Example: `example name` Name of the agent `provide_citations` boolean optional Example: `true` Whether the agent should provide in-response citations `retrieval_method` string, one of: RETRIEVAL_METHOD_UNKNOWN, RETRIEVAL_METHOD_REWRITE, RETRIEVAL_METHOD_STEP_BACK, RETRIEVAL_METHOD_SUB_QUERIES, RETRIEVAL_METHOD_NONE optional Example: `RETRIEVAL_METHOD_UNKNOWN` - RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown - RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite - RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back - RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries - RETRIEVAL_METHOD_NONE: The retrieval method is none `tags` array of string optional Example: `["example string"]` Tags associated with the agent `temperature` number (float) optional Example: `123` Temperature setting for the agent `top_p` number (float) optional Example: `123` Top_p setting for the agent `trigger_action` string optional Example: `example string` Action triggering the configuration update `version_hash` string optional Example: `example string` Version hash `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Rollback to Agent Version `/v2/gen-ai/agents/{uuid}/versions` 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` ```json { "uuid": "\"12345678-1234-1234-1234-123456789012\"", "version_hash": "c3658d8b5c05494cd03ce042926ef08157889ed54b1b74b5ee0b3d66dcee4b73" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/versions" \ -d '{ "uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "version_hash": "c3658d8b5c05494cd03ce042926ef08157889ed54b1b74b5ee0b3d66dcee4b73" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `audit_header` object optional An alternative way to provide auth information. for internal use only. **Show child properties** `actor_id` string (uint64) optional Example: `12345` `actor_ip` string optional Example: `example string` `actor_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `context_urn` string optional Example: `example string` `origin_application` string optional Example: `example string` `user_id` string (uint64) optional Example: `12345` `user_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `version_hash` string optional Example: `example string` Unique identifier **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Anthropic API Keys `/v2/gen-ai/anthropic/keys` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/anthropic/keys" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_infos` array of object optional Api key infos **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key creation date `created_by` string (uint64) optional Example: `12345` Created by user id from DO `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key deleted date `name` string optional Example: `example name` Name `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key last updated date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Anthropic API Key `/v2/gen-ai/anthropic/keys` 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` ```json { "api_key": "\"sk-ant-12345678901234567890123456789012\"", "name": "\"Production Key\"" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/anthropic/keys" \ -d '{ "api_key": "sk-ant-12345678901234567890123456789012", "name": "test-key" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Anthropic API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key creation date `created_by` string (uint64) optional Example: `12345` Created by user id from DO `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key deleted date `name` string optional Example: `example name` Name `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key last updated date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get Anthropic API Key `/v2/gen-ai/anthropic/keys/{api_key_uuid}` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Anthropic API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key creation date `created_by` string (uint64) optional Example: `12345` Created by user id from DO `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key deleted date `name` string optional Example: `example name` Name `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key last updated date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Anthropic API Key `/v2/gen-ai/anthropic/keys/{api_key_uuid}` 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` ```json { "api_key": "\"sk-ant-12345678901234567890123456789012\"", "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"", "name": "\"Production Key\"" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \ -d '{ "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4", "name": "test-key2" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Anthropic API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key creation date `created_by` string (uint64) optional Example: `12345` Created by user id from DO `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key deleted date `name` string optional Example: `example name` Name `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key last updated date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Anthropic API Key `/v2/gen-ai/anthropic/keys/{api_key_uuid}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Anthropic API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key creation date `created_by` string (uint64) optional Example: `12345` Created by user id from DO `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key deleted date `name` string optional Example: `example name` Name `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Key last updated date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List agents by Anthropic key `/v2/gen-ai/anthropic/keys/{uuid}/agents` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/agents" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true } ], "links": { "pages": { "first": "example string", "last": "example string", "next": "example string", "previous": "example string" } }, "meta": { "page": 123, "pages": 123, "total": 123 } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Custom Models `/v2/gen-ai/custom_models` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `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 `error_message` string optional Example: `example string` User-facing reason the most recent import failed; empty otherwise. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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", "error_message": "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Import Custom Model `/v2/gen-ai/custom_models/import` To import a custom model, send a POST request to `/v2/gen-ai/custom_models/import`. #### Request Body: `application/json` `accept_hf_token_storage` boolean optional Example: `true` Whether the caller accepts storage of their HuggingFace token for gated model access `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` ```json { "accept_hf_token_storage": true, "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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 `error_message` string optional Example: `example string` User-facing reason the most recent import failed; empty otherwise. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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", "error_message": "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get Custom Model `/v2/gen-ai/custom_models/{uuid}` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 `error_message` string optional Example: `example string` User-facing reason the most recent import failed; empty otherwise. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "model": { "active_deployments": [], "architecture": "example string", "context_length": 123, "cost_estimate_per_month": 123, "created_at": "2023-01-01T00:00:00Z", "description": "example string", "error_message": "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Custom Model `/v2/gen-ai/custom_models/{uuid}` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "error": "example string", "status": "DELETE_CUSTOM_MODEL_STATUS_UNSPECIFIED" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PATCH Update Custom Model Metadata `/v2/gen-ai/custom_models/{uuid}/metadata` 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` `input_modalities` array of string optional Example: `["example string"]` Optional new input modalities for the model (replaces existing list when non-empty). Spaces-imported models only. `license` string optional Example: `example string` `name` string optional Example: `example name` `output_modalities` array of string optional Example: `["example string"]` Optional new output modalities for the model (replaces existing list when non-empty). Spaces-imported models only. `parameters` string (uint64) optional Example: `12345` `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` ```json { "description": "example string", "input_modalities": [ "example string" ], "license": "example string", "name": "example name", "output_modalities": [ "example string" ], "parameters": "12345", "tags": { "tags": [ "example string" ] }, "uuid": "a1b2c3d4-..." } ``` ### cURL ```bash 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"] }, "input_modalities": ["text"], "output_modalities": ["text"], "parameters": "7000000000", "license": "apache-2.0" }' ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 `error_message` string optional Example: `example string` User-facing reason the most recent import failed; empty otherwise. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "model": { "active_deployments": [], "architecture": "example string", "context_length": 123, "cost_estimate_per_month": 123, "created_at": "2023-01-01T00:00:00Z", "description": "example string", "error_message": "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Evaluation Datasets `/v2/gen-ai/evaluation_datasets` To list evaluation datasets, send a GET request to `/v2/gen-ai/evaluation_datasets`. #### Query Parameters `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` Filter by evaluation dataset type. Default: `EVALUATION_DATASET_TYPE_UNKNOWN` `dataset_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` Filter by evaluation dataset paradigm (row/content shape). Default: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` `has_ground_truth` boolean optional Example: `true` Filter by whether the dataset includes ground-truth values. ##### Request: `/v2/gen-ai/evaluation_datasets` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_datasets" ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `evaluation_datasets` array of object optional The list of evaluation datasets. **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_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` EvaluationDatasetParadigm is the row/content shape of a dataset, orthogonal to the surface in EvaluationDatasetType (e.g. a model dataset can be single- or multi-turn). `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. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "evaluation_datasets": [ { "created_at": "2023-01-01T00:00:00Z", "dataset_name": "example name", "dataset_paradigm": "EVALUATION_DATASET_PARADIGM_SINGLE_TURN", "dataset_type": "EVALUATION_DATASET_TYPE_UNKNOWN", "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000", "file_size": "12345", "has_ground_truth": true, "row_count": 123 } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Evaluation Dataset `/v2/gen-ai/evaluation_datasets` To create an evaluation dataset, send a POST request to `/v2/gen-ai/evaluation_datasets`. #### Request Body: `application/json` `dataset_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` EvaluationDatasetParadigm is the row/content shape of a dataset, orthogonal to the surface in EvaluationDatasetType (e.g. a model dataset can be single- or multi-turn). `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` ```json { "dataset_paradigm": "EVALUATION_DATASET_PARADIGM_SINGLE_TURN", "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 ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_datasets" \ -d '{ "name": "dataset.csv", "file_upload_dataset": { "original_file_name": "dataset.csv", "stored_object_key": "123abc", "size_in_bytes": 255 } }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `evaluation_dataset_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Evaluation dataset uuid. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "evaluation_dataset_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` 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` ```json { "files": [ { "file_name": "example name", "file_size": "12345" } ] } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_datasets/file_upload_presigned_urls" \ -d '{ "files": [{ "file_name": "dataset.csv", "file_size": 2048 }] }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `request_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` The ID generated for the request for Presigned URLs. `uploads` array of object optional A list of generated presigned URLs and object keys, one per file. **Show child properties** `expires_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` The time the url expires at. `object_key` string optional Example: `example string` The unique object key to store the file as. `original_file_name` string optional Example: `example name` The original file name. `presigned_url` string optional Example: `example string` The actual presigned URL the client can use to upload the file directly. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Evaluation Dataset `/v2/gen-ai/evaluation_datasets/{dataset_uuid}` To delete an evaluation dataset, send a DELETE request to `/v2/genai/evaluation_datasets/{dataset_uuid}`. This works for both model and agent evaluation datasets. #### Path Parameters `dataset_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the evaluation dataset to delete. ##### Request: `/v2/gen-ai/evaluation_datasets/{dataset_uuid}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_datasets/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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get Download URL for Evaluation Dataset `/v2/gen-ai/evaluation_datasets/{dataset_uuid}/download_url` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "download_url": "example string", "expires_at": "2023-01-01T00:00:00Z" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Evaluation Metrics `/v2/gen-ai/evaluation_metrics` To list all evaluation metrics, send a GET request to `/v2/gen-ai/evaluation_metrics`. ##### Request: `/v2/gen-ai/evaluation_metrics` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_metrics" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `metrics` array of object optional **Show child properties** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. **Show child properties** `eval_preset_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique identifier of the saved model evaluation preset that references the metric. `name` string optional Example: `"My evaluation preset"` Display name of the saved model evaluation preset. `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "metrics": [ { "associated_presets": [], "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, "source": "EVALUATION_METRIC_SOURCE_UNSPECIFIED" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Custom Evaluation Metric `/v2/gen-ai/custom_evaluation_metrics` To create a custom LLM-as-judge metric for model evaluation, send a POST request to `/v2/gen-ai/custom_evaluation_metrics`. #### Request Body: `application/json` `config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `description` string optional Example: `"Scores adherence to our support macros"` `metric_name` string optional Example: `"My domain tone metric"` ##### Request: `/v2/gen-ai/custom_evaluation_metrics` ### Payload Content type `application/json` ```json { "config": { "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "requires_ground_truth": true, "scoring_prompt": "example string", "updated_at": "2023-01-01T00:00:00Z" }, "description": "\"Scores adherence to our support macros\"", "metric_name": "\"My domain tone metric\"" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/custom_evaluation_metrics" \ -d '{ "metric_name": "My domain tone metric", "description": "Scores adherence to our support macros", "config": { "requires_ground_truth": true, "scoring_prompt": "Grade for brand tone and factuality." } }' ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `metric` object optional **Show child properties** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. **Show child properties** `eval_preset_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique identifier of the saved model evaluation preset that references the metric. `name` string optional Example: `"My evaluation preset"` Display name of the saved model evaluation preset. `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "metric": { "associated_presets": [], "category": "METRIC_CATEGORY_UNSPECIFIED", "custom_eval_config": { "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "requires_ground_truth": true, "scoring_prompt": "example string", "updated_at": "2023-01-01T00:00:00Z" }, "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, "source": "EVALUATION_METRIC_SOURCE_UNSPECIFIED" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Custom Evaluation Metric `/v2/gen-ai/custom_evaluation_metrics/{metric_uuid}` To update a custom metric (issuing a new metric UUID), send a PUT request to `/v2/gen-ai/custom_evaluation_metrics/{metric_uuid}`. #### Path Parameters `metric_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the custom metric to update. #### Request Body: `application/json` `config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `description` string optional Example: `example string` `metric_name` string optional Example: `"My domain tone metric"` `metric_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` ##### Request: `/v2/gen-ai/custom_evaluation_metrics/{metric_uuid}` ### Payload Content type `application/json` ```json { "config": { "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "requires_ground_truth": true, "scoring_prompt": "example string", "updated_at": "2023-01-01T00:00:00Z" }, "description": "example string", "metric_name": "\"My domain tone metric\"", "metric_uuid": "\"12345678-1234-1234-1234-123456789012\"" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/custom_evaluation_metrics/e51dba65-cf7a-11ef-bf8f-4e013e2ddde4" \ -d '{ "metric_uuid": "e51dba65-cf7a-11ef-bf8f-4e013e2ddde4", "metric_name": "My domain tone metric", "description": "Scores adherence to our support macros", "config": { "requires_ground_truth": true, "scoring_prompt": "Grade for brand tone and factuality." } }' ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `metric` object optional **Show child properties** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. **Show child properties** `eval_preset_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique identifier of the saved model evaluation preset that references the metric. `name` string optional Example: `"My evaluation preset"` Display name of the saved model evaluation preset. `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "metric": { "associated_presets": [], "category": "METRIC_CATEGORY_UNSPECIFIED", "custom_eval_config": { "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "requires_ground_truth": true, "scoring_prompt": "example string", "updated_at": "2023-01-01T00:00:00Z" }, "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, "source": "EVALUATION_METRIC_SOURCE_UNSPECIFIED" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Custom Evaluation Metric `/v2/gen-ai/custom_evaluation_metrics/{metric_uuid}` To soft-delete a custom model evaluation metric, send a DELETE request to `/v2/gen-ai/custom_evaluation_metrics/{metric_uuid}`. #### Path Parameters `metric_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the custom metric to delete. ##### Request: `/v2/gen-ai/custom_evaluation_metrics/{metric_uuid}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/custom_evaluation_metrics/e51dba65-cf7a-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Run an Evaluation Test Case `/v2/gen-ai/evaluation_runs` 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` ```json { "agent_deployment_names": [ "example string" ], "agent_uuids": [ "example string" ], "run_name": "Evaluation Run Name", "test_case_uuid": "\"12345678-1234-1234-1234-123456789012\"" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_runs" \ -d '{ "test_case_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "agent_uuids": ["1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "2b418231-b7d6-11ef-bf8f-4e013e2ddde4"], "run_name": "My Evaluation Run", }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `evaluation_run_uuids` array of string optional Example: `["example string"]` **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "evaluation_run_uuids": [ "example string" ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Information About an Existing Evaluation Run `/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_runs/9758a232-b351-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `example@example.com` `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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `string_value` string optional Example: `example string` The value of the metric as a string. `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Run start time. `status` string (enum) optional Example: `EVALUATION_RUN_STATUS_UNSPECIFIED` Evaluation Run Statuses `test_case_description` string optional Example: `example string` Test case description. `test_case_name` string optional Example: `example name` Test case name. `test_case_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Test-case UUID. `test_case_version` integer (int64) optional Example: `123` Test-case-version. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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": "example@example.com", "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_uuid": "123e4567-e89b-12d3-a456-426614174000", "metric_value_type": "METRIC_VALUE_TYPE_UNSPECIFIED", "number_value": 123, "reasoning": "example string", "status": "EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Results of an Evaluation Run `/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_runs/9758a232-b351-11ef-bf8f-4e013e2ddde4/results" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `example@example.com` `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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `string_value` string optional Example: `example string` The value of the metric as a string. `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Run start time. `status` string (enum) optional Example: `EVALUATION_RUN_STATUS_UNSPECIFIED` Evaluation Run Statuses `test_case_description` string optional Example: `example string` Test case description. `test_case_name` string optional Example: `example name` Test case name. `test_case_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Test-case UUID. `test_case_version` integer (int64) optional Example: `123` Test-case-version. `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `prompts` array of object optional The prompt level results. **Show child properties** `evaluation_trace_spans` array of object optional The evaluated trace spans. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When the span was created `input` object optional Input data for the span (flexible structure - can be messages array, string, etc.) `name` string optional Example: `example name` Name/identifier for the span `output` object optional Output data from the span (flexible structure - can be message, string, etc.) `retriever_chunks` array of object optional Any retriever span chunks that were included as part of the span. **Show child properties** `chunk_usage_pct` number (double) optional Example: `123` The usage percentage of the chunk. `chunk_used` boolean optional Example: `true` Indicates if the chunk was used in the prompt. `index_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` The index uuid (Knowledge Base) of the chunk. `source_name` string optional Example: `example name` The source name for the chunk, e.g., the file name or document title. `text` string optional Example: `example string` Text content of the chunk. `span_level_metric_results` array of object optional The span-level metric results. **Show child properties** `error_description` string optional Example: `example string` Error description if the metric could not be calculated. `metric_name` string optional Example: `example name` Metric name `metric_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `llm` object optional LLM span *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `retriever` object optional Retriever span *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `tool` object optional Tool span *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `string_value` string optional Example: `example string` The value of the metric as a string. `trace_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` The trace id for the prompt. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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": "example@example.com", "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_uuid": "123e4567-e89b-12d3-a456-426614174000", "metric_value_type": "METRIC_VALUE_TYPE_UNSPECIFIED", "number_value": 123, "reasoning": "example string", "status": "EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_runs/9758a232-b351-11ef-bf8f-4e013e2ddde4/results/c441bf77-81d6-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `llm` object optional LLM span *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `retriever` object optional Retriever span *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `tool` object optional Tool span *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `string_value` string optional Example: `example string` The value of the metric as a string. `trace_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` The trace id for the prompt. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Evaluation Test Cases `/v2/gen-ai/evaluation_test_cases` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `example@example.com` `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_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` EvaluationDatasetParadigm is the row/content shape of a dataset, orthogonal to the surface in EvaluationDatasetType (e.g. a model dataset can be single- or multi-turn). `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** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. **Show child properties** `eval_preset_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique identifier of the saved model evaluation preset that references the metric. `name` string optional Example: `"My evaluation preset"` Display name of the saved model evaluation preset. `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "evaluation_test_cases": [ { "archived_at": "2023-01-01T00:00:00Z", "created_at": "2023-01-01T00:00:00Z", "created_by_user_email": "example@example.com", "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": "example@example.com", "updated_by_user_id": "12345", "version": 123 } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Evaluation Test Case. `/v2/gen-ai/evaluation_test_cases` 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` ```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 ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases" \ -d '{ "name": "Test Case", "description": "Description of the test case", "dataset_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "metrics": ["1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "2b418231-b7d6-11ef-bf8f-4e013e2ddde4"], "star_metric": { "metric_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "name": "Retrieved chunk usage", "success_threshold_pct": 80 }, "workspace_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `test_case_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Test‑case UUID. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/evaluation_runs" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `example@example.com` `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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `string_value` string optional Example: `example string` The value of the metric as a string. `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Run start time. `status` string (enum) optional Example: `EVALUATION_RUN_STATUS_UNSPECIFIED` Evaluation Run Statuses `test_case_description` string optional Example: `example string` Test case description. `test_case_name` string optional Example: `example name` Test case name. `test_case_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Test-case UUID. `test_case_version` integer (int64) optional Example: `123` Test-case-version. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases/9758a232-b351-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `example@example.com` `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_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` EvaluationDatasetParadigm is the row/content shape of a dataset, orthogonal to the surface in EvaluationDatasetType (e.g. a model dataset can be single- or multi-turn). `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** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. **Show child properties** `eval_preset_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique identifier of the saved model evaluation preset that references the metric. `name` string optional Example: `"My evaluation preset"` Display name of the saved model evaluation preset. `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "evaluation_test_case": { "archived_at": "2023-01-01T00:00:00Z", "created_at": "2023-01-01T00:00:00Z", "created_by_user_email": "example@example.com", "created_by_user_id": "12345", "dataset": { "created_at": "2023-01-01T00:00:00Z", "dataset_name": "example name", "dataset_paradigm": "EVALUATION_DATASET_PARADIGM_SINGLE_TURN", "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": "example@example.com", "updated_by_user_id": "12345", "version": 123 } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update an Evaluation Test Case. `/v2/gen-ai/evaluation_test_cases/{test_case_uuid}` 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` ```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 ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases/e51dba65-cf7a-11ef-bf8f-4e013e2ddde4" \ -d '{ "test_case_uuid": "e51dba65-cf7a-11ef-bf8f-4e013e2ddde4", "name": "Updated Test Case", "description": "Updated description of the test case", "dataset_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "metrics": ["1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "2b418231-b7d6-11ef-bf8f-4e013e2ddde4"], "star_metric": { "metric_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "name": "Retrieved chunk usage", "success_threshold_pct": 80 } }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `test_case_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `version` integer (int32) optional Example: `123` The new verson of the test case. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000", "version": 123 } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Indexing Jobs for a Knowledge Base `/v2/gen-ai/indexing_jobs` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/indexing_jobs" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `jobs` array of object optional The indexing jobs **Show child properties** `completed_datasources` integer (int64) optional Example: `123` Number of datasources indexed completed `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date / time `data_source_jobs` array of object optional Details on Data Sources included in the Indexing Job **Show child properties** `completed_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source completed indexing `data_source_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid of the indexed data source `error_details` string optional Example: `example string` A detailed error description `error_msg` string optional Example: `example string` A string code provinding a hint which part of the system experienced an error `failed_item_count` string (uint64) optional Example: `12345` Total count of files that have failed `indexed_file_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `indexed_item_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `removed_item_count` string (uint64) optional Example: `12345` Total count of files that have been removed `skipped_item_count` string (uint64) optional Example: `12345` Total count of files that have been skipped `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source started indexing `status` string (enum) optional Example: `DATA_SOURCE_STATUS_UNKNOWN` `total_bytes` string (uint64) optional Example: `12345` Total size of files in data source in bytes `total_bytes_indexed` string (uint64) optional Example: `12345` Total size of files in data source in bytes that have been indexed `total_file_count` string (uint64) optional Example: `12345` Total file count in the data source `data_source_uuids` array of string optional Example: `["example string"]` `finished_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `is_report_available` boolean optional Example: `true` Boolean value to determine if the indexing job details are available `knowledge_base_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Knowledge base id `phase` string (enum) optional Example: `BATCH_JOB_PHASE_UNKNOWN` `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `status` string (enum) optional Example: `INDEX_JOB_STATUS_UNKNOWN` `tokens` integer (int64) optional Example: `123` Number of tokens \[This field is deprecated] `total_datasources` integer (int64) optional Example: `123` Number of datasources being indexed `total_tokens` string (uint64) optional Example: `12345` Total Tokens Consumed By the Indexing Job `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Last modified `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Start Indexing Job for a Knowledge Base `/v2/gen-ai/indexing_jobs` 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` ```json { "data_source_uuids": [ "example string" ], "knowledge_base_uuid": "\"12345678-1234-1234-1234-123456789012\"" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/indexing_jobs" \ -d '{ "knowledge_base_uuid": "9758a232-b351-11ef-bf8f-4e013e2ddde4", "data_source_uuids": [ "9a825ee0-bbb1-11ef-bf8f-4e013e2ddde4" ] }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `job` object optional IndexingJob description **Show child properties** `completed_datasources` integer (int64) optional Example: `123` Number of datasources indexed completed `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date / time `data_source_jobs` array of object optional Details on Data Sources included in the Indexing Job **Show child properties** `completed_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source completed indexing `data_source_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid of the indexed data source `error_details` string optional Example: `example string` A detailed error description `error_msg` string optional Example: `example string` A string code provinding a hint which part of the system experienced an error `failed_item_count` string (uint64) optional Example: `12345` Total count of files that have failed `indexed_file_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `indexed_item_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `removed_item_count` string (uint64) optional Example: `12345` Total count of files that have been removed `skipped_item_count` string (uint64) optional Example: `12345` Total count of files that have been skipped `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source started indexing `status` string (enum) optional Example: `DATA_SOURCE_STATUS_UNKNOWN` `total_bytes` string (uint64) optional Example: `12345` Total size of files in data source in bytes `total_bytes_indexed` string (uint64) optional Example: `12345` Total size of files in data source in bytes that have been indexed `total_file_count` string (uint64) optional Example: `12345` Total file count in the data source `data_source_uuids` array of string optional Example: `["example string"]` `finished_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `is_report_available` boolean optional Example: `true` Boolean value to determine if the indexing job details are available `knowledge_base_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Knowledge base id `phase` string (enum) optional Example: `BATCH_JOB_PHASE_UNKNOWN` `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `status` string (enum) optional Example: `INDEX_JOB_STATUS_UNKNOWN` `tokens` integer (int64) optional Example: `123` Number of tokens \[This field is deprecated] `total_datasources` integer (int64) optional Example: `123` Number of datasources being indexed `total_tokens` string (uint64) optional Example: `12345` Total Tokens Consumed By the Indexing Job `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Last modified `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/indexing_jobs/9758a232-b351-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `indexed_data_sources` array of object optional **Show child properties** `completed_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source completed indexing `data_source_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid of the indexed data source `error_details` string optional Example: `example string` A detailed error description `error_msg` string optional Example: `example string` A string code provinding a hint which part of the system experienced an error `failed_item_count` string (uint64) optional Example: `12345` Total count of files that have failed `indexed_file_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `indexed_item_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `removed_item_count` string (uint64) optional Example: `12345` Total count of files that have been removed `skipped_item_count` string (uint64) optional Example: `12345` Total count of files that have been skipped `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source started indexing `status` string (enum) optional Example: `DATA_SOURCE_STATUS_UNKNOWN` `total_bytes` string (uint64) optional Example: `12345` Total size of files in data source in bytes `total_bytes_indexed` string (uint64) optional Example: `12345` Total size of files in data source in bytes that have been indexed `total_file_count` string (uint64) optional Example: `12345` Total file count in the data source **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` 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 ```bash curl --location --request GET 'https://api.digitalocean.com/v2/gen-ai/indexing_jobs/6b090372-a8c3-11f0-b542-ca68c578b04b/details_signed_url' \ --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' \ --header 'Content-Type: application/json' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `signed_url` string optional Example: `example string` The signed url for downloading the indexing job details **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "signed_url": "example string" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Status of Indexing Job for a Knowledge Base `/v2/gen-ai/indexing_jobs/{uuid}` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/indexing_jobs/9758a232-b351-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `job` object optional IndexingJob description **Show child properties** `completed_datasources` integer (int64) optional Example: `123` Number of datasources indexed completed `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date / time `data_source_jobs` array of object optional Details on Data Sources included in the Indexing Job **Show child properties** `completed_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source completed indexing `data_source_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid of the indexed data source `error_details` string optional Example: `example string` A detailed error description `error_msg` string optional Example: `example string` A string code provinding a hint which part of the system experienced an error `failed_item_count` string (uint64) optional Example: `12345` Total count of files that have failed `indexed_file_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `indexed_item_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `removed_item_count` string (uint64) optional Example: `12345` Total count of files that have been removed `skipped_item_count` string (uint64) optional Example: `12345` Total count of files that have been skipped `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source started indexing `status` string (enum) optional Example: `DATA_SOURCE_STATUS_UNKNOWN` `total_bytes` string (uint64) optional Example: `12345` Total size of files in data source in bytes `total_bytes_indexed` string (uint64) optional Example: `12345` Total size of files in data source in bytes that have been indexed `total_file_count` string (uint64) optional Example: `12345` Total file count in the data source `data_source_uuids` array of string optional Example: `["example string"]` `finished_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `is_report_available` boolean optional Example: `true` Boolean value to determine if the indexing job details are available `knowledge_base_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Knowledge base id `phase` string (enum) optional Example: `BATCH_JOB_PHASE_UNKNOWN` `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `status` string (enum) optional Example: `INDEX_JOB_STATUS_UNKNOWN` `tokens` integer (int64) optional Example: `123` Number of tokens \[This field is deprecated] `total_datasources` integer (int64) optional Example: `123` Number of datasources being indexed `total_tokens` string (uint64) optional Example: `12345` Total Tokens Consumed By the Indexing Job `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Last modified `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Cancel Indexing Job for a Knowledge Base `/v2/gen-ai/indexing_jobs/{uuid}/cancel` 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` ```json { "uuid": "\"12345678-1234-1234-1234-123456789012\"" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/indexing_jobs/79ca9798-cf7d-11ef-bf8f-4e013e2ddde4/cancel" \ -d '{ "uuid": "79ca9798-cf7d-11ef-bf8f-4e013e2ddde4" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `job` object optional IndexingJob description **Show child properties** `completed_datasources` integer (int64) optional Example: `123` Number of datasources indexed completed `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date / time `data_source_jobs` array of object optional Details on Data Sources included in the Indexing Job **Show child properties** `completed_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source completed indexing `data_source_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid of the indexed data source `error_details` string optional Example: `example string` A detailed error description `error_msg` string optional Example: `example string` A string code provinding a hint which part of the system experienced an error `failed_item_count` string (uint64) optional Example: `12345` Total count of files that have failed `indexed_file_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `indexed_item_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `removed_item_count` string (uint64) optional Example: `12345` Total count of files that have been removed `skipped_item_count` string (uint64) optional Example: `12345` Total count of files that have been skipped `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source started indexing `status` string (enum) optional Example: `DATA_SOURCE_STATUS_UNKNOWN` `total_bytes` string (uint64) optional Example: `12345` Total size of files in data source in bytes `total_bytes_indexed` string (uint64) optional Example: `12345` Total size of files in data source in bytes that have been indexed `total_file_count` string (uint64) optional Example: `12345` Total file count in the data source `data_source_uuids` array of string optional Example: `["example string"]` `finished_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `is_report_available` boolean optional Example: `true` Boolean value to determine if the indexing job details are available `knowledge_base_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Knowledge base id `phase` string (enum) optional Example: `BATCH_JOB_PHASE_UNKNOWN` `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `status` string (enum) optional Example: `INDEX_JOB_STATUS_UNKNOWN` `tokens` integer (int64) optional Example: `123` Number of tokens \[This field is deprecated] `total_datasources` integer (int64) optional Example: `123` Number of datasources being indexed `total_tokens` string (uint64) optional Example: `12345` Total Tokens Consumed By the Indexing Job `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Last modified `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Knowledge Bases `/v2/gen-ai/knowledge_bases` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/knowledge_bases" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create a Knowledge Base `/v2/gen-ai/knowledge_bases` 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](#create_knowledge_base_data_source). When provided, see [Organize Data Sources](https://docs.digitalocean.com/products/inference/how-to/create-manage-agent-knowledge-bases/index.html.md#add-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](https://docs.digitalocean.com/products/genai-platform/details/models/index.html.md#embedding-models). `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` ```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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` 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` ```json { "files": [ { "file_name": "example name", "file_size": "12345" } ] } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/data_sources/file_upload_presigned_urls" \ -d '{ "files": [{ "file_name": "dataset.csv", "file_size": 2048 }] }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `request_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` The ID generated for the request for Presigned URLs. `uploads` array of object optional A list of generated presigned URLs and object keys, one per file. **Show child properties** `expires_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` The time the url expires at. `object_key` string optional Example: `example string` The unique object key to store the file as. `original_file_name` string optional Example: `example name` The original file name. `presigned_url` string optional Example: `example string` The actual presigned URL the client can use to upload the file directly. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9758a232-b351-11ef-bf8f-4e013e2ddde4/data_sources" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `knowledge_base_data_sources` array of object optional The data sources **Show child properties** `aws_data_source` object optional AWS S3 Data Source for Display **Show child properties** `bucket_name` string optional Example: `example name` Spaces bucket name `item_path` string optional Example: `example string` `region` string optional Example: `example string` Region of bucket `bucket_name` string optional Example: `example name` Name of storage bucket - Deprecated, moved to data_source_details `chunking_algorithm` string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional Example: `CHUNKING_ALGORITHM_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` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` To add a data source to a knowledge base, send a POST request to `/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources`. #### Path Parameters `knowledge_base_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` Knowledge base id #### Request Body: `application/json` `aws_data_source` object optional AWS S3 Data Source **Show child properties** `bucket_name` string optional Example: `example name` Spaces bucket name `item_path` string optional Example: `example string` `key_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` The AWS Key ID `region` string optional Example: `example string` Region of bucket `secret_key` string optional Example: `example string` The AWS Secret Key `chunking_algorithm` string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional Example: `CHUNKING_ALGORITHM_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` ```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 ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/20cd8434-6ea1-11f0-bf8f-4e013e2ddde4/data_sources" \ -d '{ "knowledge_base_uuid": "20cd8434-6ea1-11f0-bf8f-4e013e2ddde4", "web_crawler_data_source": { "base_url": "https://example.com", "crawling_option": "SCOPED", "embed_media": false, "exclude_tags": ["nav","footer","header","aside","script","style","form","iframe", "noscript"] }, "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED", "chunking_options": { "max_chunk_size": 500 } }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `knowledge_base_data_source` object optional Data Source configuration for Knowledge Bases **Show child properties** `aws_data_source` object optional AWS S3 Data Source for Display **Show child properties** `bucket_name` string optional Example: `example name` Spaces bucket name `item_path` string optional Example: `example string` `region` string optional Example: `example string` Region of bucket `bucket_name` string optional Example: `example name` Name of storage bucket - Deprecated, moved to data_source_details `chunking_algorithm` string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional Example: `CHUNKING_ALGORITHM_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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` To update a data source (e.g. chunking options), send a PUT request to `/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources/{data_source_uuid}`. #### Path Parameters `knowledge_base_uuid` string required Example: `123e4567-e89b-12d3-a456-426614174000` Knowledge Base ID (Path Parameter) `data_source_uuid` string required Example: `123e4567-e89b-12d3-a456-426614174000` Data Source ID (Path Parameter) #### Request Body: `application/json` `chunking_algorithm` string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional Example: `CHUNKING_ALGORITHM_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` ```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 ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/12345678-1234-1234-1234-123456789012/data_sources/98765432-1234-1234-1234-123456789012" \ -d '{ "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED", "chunking_options": { "max_chunk_size": 500 } }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `knowledge_base_data_source` object optional Data Source configuration for Knowledge Bases **Show child properties** `aws_data_source` object optional AWS S3 Data Source for Display **Show child properties** `bucket_name` string optional Example: `example name` Spaces bucket name `item_path` string optional Example: `example string` `region` string optional Example: `example string` Region of bucket `bucket_name` string optional Example: `example name` Name of storage bucket - Deprecated, moved to data_source_details `chunking_algorithm` string, one of: CHUNKING_ALGORITHM_UNKNOWN, CHUNKING_ALGORITHM_SECTION_BASED, CHUNKING_ALGORITHM_HIERARCHICAL, CHUNKING_ALGORITHM_SEMANTIC, CHUNKING_ALGORITHM_FIXED_LENGTH optional Example: `CHUNKING_ALGORITHM_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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4/data_sources/bd2a2db5-b8b0-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `data_source_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Data source id `knowledge_base_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Knowledge base id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "data_source_uuid": "123e4567-e89b-12d3-a456-426614174000", "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` 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 ```bash curl --location --request GET 'https://api.digitalocean.com/v2/gen-ai/knowledge_bases/1139121f-a860-11f0-b542-ca68c578b04b/indexing_jobs' \ --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' \ --header 'Content-Type: application/json' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `jobs` array of object optional The indexing jobs **Show child properties** `completed_datasources` integer (int64) optional Example: `123` Number of datasources indexed completed `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date / time `data_source_jobs` array of object optional Details on Data Sources included in the Indexing Job **Show child properties** `completed_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source completed indexing `data_source_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid of the indexed data source `error_details` string optional Example: `example string` A detailed error description `error_msg` string optional Example: `example string` A string code provinding a hint which part of the system experienced an error `failed_item_count` string (uint64) optional Example: `12345` Total count of files that have failed `indexed_file_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `indexed_item_count` string (uint64) optional Example: `12345` Total count of files that have been indexed `removed_item_count` string (uint64) optional Example: `12345` Total count of files that have been removed `skipped_item_count` string (uint64) optional Example: `12345` Total count of files that have been skipped `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Timestamp when data source started indexing `status` string (enum) optional Example: `DATA_SOURCE_STATUS_UNKNOWN` `total_bytes` string (uint64) optional Example: `12345` Total size of files in data source in bytes `total_bytes_indexed` string (uint64) optional Example: `12345` Total size of files in data source in bytes that have been indexed `total_file_count` string (uint64) optional Example: `12345` Total file count in the data source `data_source_uuids` array of string optional Example: `["example string"]` `finished_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `is_report_available` boolean optional Example: `true` Boolean value to determine if the indexing job details are available `knowledge_base_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Knowledge base id `phase` string (enum) optional Example: `BATCH_JOB_PHASE_UNKNOWN` `started_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `status` string (enum) optional Example: `INDEX_JOB_STATUS_UNKNOWN` `tokens` integer (int64) optional Example: `123` Number of tokens \[This field is deprecated] `total_datasources` integer (int64) optional Example: `123` Number of datasources being indexed `total_tokens` string (uint64) optional Example: `12345` Total Tokens Consumed By the Indexing Job `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Last modified `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Information About an Existing Knowledge Base `/v2/gen-ai/knowledge_bases/{uuid}` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9758a232-b351-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update a Knowledge Base `/v2/gen-ai/knowledge_bases/{uuid}` 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` ```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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete a Knowledge Base `/v2/gen-ai/knowledge_bases/{uuid}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/8241f44e-b0da-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` The id of the deleted knowledge base **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` 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` ```json { "files": [ { "file_name": "example name", "file_size": "12345" } ] } ``` ### cURL ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `request_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` The ID generated for the request for Presigned URLs. `uploads` array of object optional A list of generated presigned URLs and object keys, one per file. **Show child properties** `expires_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` The time the url expires at. `object_key` string optional Example: `example string` The unique object key to store the file as. `original_file_name` string optional Example: `example name` The original file name. `presigned_url` string optional Example: `example string` The actual presigned URL the client can use to upload the file directly. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Model Evaluation Metrics `/v2/gen-ai/model_evaluation_metrics` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. **Show child properties** `eval_preset_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique identifier of the saved model evaluation preset that references the metric. `name` string optional Example: `"My evaluation preset"` Display name of the saved model evaluation preset. `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "metrics": [ { "associated_presets": [], "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, "source": "EVALUATION_METRIC_SOURCE_UNSPECIFIED" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Model Evaluation Presets `/v2/gen-ai/model_evaluation_presets` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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** `candidate_inference_config` object optional Inference configuration for the candidate model during evaluation. **Show child properties** `max_tokens` integer (int64) optional Example: `123` `reasoning_effort` string optional Example: `low` Reasoning effort for reasoning-capable models (e.g. "low", "medium", "high"). Validated against the candidate model's supported values; a model that advertises none rejects this field. `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. Empty when the CANDIDATE section was not saved. `candidate_model_source` string, one of: CANDIDATE_MODEL_SOURCE_SERVERLESS, CANDIDATE_MODEL_SOURCE_DEDICATED, CANDIDATE_MODEL_SOURCE_ROUTER, CANDIDATE_MODEL_SOURCE_AGENT optional Example: `CANDIDATE_MODEL_SOURCE_SERVERLESS` Whether the candidate is a served model (serverless platform, a dedicated deployment, or a model router) or an OHS-hosted agent config. `candidate_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the candidate model stored on this preset. Empty when the CANDIDATE section was not saved. For DEDICATED candidates this is the dedicated inference deployment UUID. `candidate_system_prompt` string optional Example: `2023-01-01` System prompt / instructions to send to the candidate model. Empty when the SYSTEM_PROMPT section was not saved (check `saved_sections`). `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` Display name of the dataset stored on this preset. Empty when the DATASET section was not saved or the dataset no longer exists. `dataset_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the dataset stored on this preset. Empty when the DATASET section was not saved (check `saved_sections`). `eval_preset_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the evaluation preset. `judge_model_name` string optional Example: `example name` Display name of the judge model stored on this preset. Empty when the JUDGE section was not saved or the model no longer exists. `judge_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the judge model stored on this preset. Empty when the JUDGE section was not saved (check `saved_sections`). `metrics` array of object optional Metrics selected for this preset. Empty when the METRICS section was not saved. **Show child properties** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. **Show child properties** `eval_preset_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique identifier of the saved model evaluation preset that references the metric. `name` string optional Example: `"My evaluation preset"` Display name of the saved model evaluation preset. `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `name` string optional Example: `example name` Name of the evaluation preset. `saved_sections` array of string (enum) optional Example: `["PRESET_SAVE_SECTION_CANDIDATE","PRESET_SAVE_SECTION_METRICS"]` Sections of the inline evaluation config that were persisted when this preset was created. Use this to tell "section was saved with an empty value" apart from "section was not saved" — scalar fields like `dataset_uuid` or `candidate_system_prompt` are always emitted as the empty string when the section was not saved. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "presets": [ { "candidate_model_name": "example name", "candidate_model_source": "CANDIDATE_MODEL_SOURCE_SERVERLESS", "candidate_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "candidate_system_prompt": "2023-01-01", "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", "saved_sections": [ "PRESET_SAVE_SECTION_CANDIDATE", "PRESET_SAVE_SECTION_METRICS" ] } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Model Evaluation Preset `/v2/gen-ai/model_evaluation_presets/{eval_preset_uuid}` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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. Each section (dataset, judge, metrics, candidate, system prompt) is independent and may be empty; sections the preset omits must be supplied inline on the run that references it. Use `saved_sections` to tell "section saved with empty value" apart from "section not saved at all" — each section's scalar fields are left empty when the section was not saved. **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` `reasoning_effort` string optional Example: `low` Reasoning effort for reasoning-capable models (e.g. "low", "medium", "high"). Validated against the candidate model's supported values; a model that advertises none rejects this field. `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. Empty when the CANDIDATE section was not saved. `candidate_model_source` string, one of: CANDIDATE_MODEL_SOURCE_SERVERLESS, CANDIDATE_MODEL_SOURCE_DEDICATED, CANDIDATE_MODEL_SOURCE_ROUTER, CANDIDATE_MODEL_SOURCE_AGENT optional Example: `CANDIDATE_MODEL_SOURCE_SERVERLESS` Whether the candidate is a served model (serverless platform, a dedicated deployment, or a model router) or an OHS-hosted agent config. `candidate_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the candidate model stored on this preset. Empty when the CANDIDATE section was not saved. For DEDICATED candidates this is the dedicated inference deployment UUID. `candidate_system_prompt` string optional Example: `2023-01-01` System prompt / instructions to send to the candidate model. Empty when the SYSTEM_PROMPT section was not saved (check `saved_sections`). `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` Display name of the dataset stored on this preset. Empty when the DATASET section was not saved or the dataset no longer exists. `dataset_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the dataset stored on this preset. Empty when the DATASET section was not saved (check `saved_sections`). `eval_preset_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the evaluation preset. `judge_model_name` string optional Example: `example name` Display name of the judge model stored on this preset. Empty when the JUDGE section was not saved or the model no longer exists. `judge_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the judge model stored on this preset. Empty when the JUDGE section was not saved (check `saved_sections`). `metrics` array of object optional Metrics selected for this preset. Empty when the METRICS section was not saved. **Show child properties** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. **Show child properties** `eval_preset_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique identifier of the saved model evaluation preset that references the metric. `name` string optional Example: `"My evaluation preset"` Display name of the saved model evaluation preset. `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `name` string optional Example: `example name` Name of the evaluation preset. `saved_sections` array of string (enum) optional Example: `["PRESET_SAVE_SECTION_CANDIDATE","PRESET_SAVE_SECTION_METRICS"]` Sections of the inline evaluation config that were persisted when this preset was created. Use this to tell "section was saved with an empty value" apart from "section was not saved" — scalar fields like `dataset_uuid` or `candidate_system_prompt` are always emitted as the empty string when the section was not saved. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "preset": { "candidate_inference_config": { "max_tokens": 123, "reasoning_effort": "low", "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", "candidate_system_prompt": "2023-01-01", "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", "saved_sections": [ "PRESET_SAVE_SECTION_CANDIDATE", "PRESET_SAVE_SECTION_METRICS" ], "star_metric": { "metric_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name", "success_threshold": 123, "success_threshold_pct": 123 } } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Model Evaluation Preset `/v2/gen-ai/model_evaluation_presets/{eval_preset_uuid}` To delete a saved model evaluation preset, send a DELETE request to `/v2/gen-ai/model_evaluation_presets/{eval_preset_uuid}`. #### Path Parameters `eval_preset_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the evaluation preset to delete. ##### Request: `/v2/gen-ai/model_evaluation_presets/{eval_preset_uuid}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/model_evaluation_presets/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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Model Evaluation Runs `/v2/gen-ai/model_evaluation_runs` 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. `statuses` array of string (enum) optional Example: `["MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED"]` Filter by one or more statuses. Empty means no status filter. `candidate_types` array of string, one of: CANDIDATE_MODEL_SOURCE_SERVERLESS, CANDIDATE_MODEL_SOURCE_DEDICATED, CANDIDATE_MODEL_SOURCE_ROUTER optional Example: `["CANDIDATE_MODEL_SOURCE_SERVERLESS"]` Filter by one or more candidate model source types (serverless, dedicated, router). Empty means no candidate-type filter. `search` string optional Example: `example string` Free-text search across the eval run name, candidate model name and dataset name (case-insensitive substring match). Empty means no search. `sort_by` string, one of: MODEL_EVALUATION_RUN_SORT_FIELD_UNSPECIFIED, MODEL_EVALUATION_RUN_SORT_FIELD_CREATED_AT, MODEL_EVALUATION_RUN_SORT_FIELD_STATUS optional Example: `MODEL_EVALUATION_RUN_SORT_FIELD_UNSPECIFIED` Field to sort by. Defaults to creation date when unspecified. Default: `MODEL_EVALUATION_RUN_SORT_FIELD_UNSPECIFIED` `sort_direction` string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Example: `SORT_DIRECTION_UNSPECIFIED` Sort direction. Defaults to descending when unspecified. Default: `SORT_DIRECTION_UNSPECIFIED` ##### Request: `/v2/gen-ai/model_evaluation_runs` ### cURL ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `available_candidate_types` array of string, one of: CANDIDATE_MODEL_SOURCE_SERVERLESS, CANDIDATE_MODEL_SOURCE_DEDICATED, CANDIDATE_MODEL_SOURCE_ROUTER, CANDIDATE_MODEL_SOURCE_AGENT optional Full set of candidate model source types the FE can offer in the candidate-type filter UI. `available_statuses` array of string (enum) optional Full set of statuses the FE can offer in the status filter UI. Returned on every list call so clients never need to hardcode the enum values. `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `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, CANDIDATE_MODEL_SOURCE_AGENT optional Example: `CANDIDATE_MODEL_SOURCE_SERVERLESS` Whether the candidate is a served model (serverless platform, a dedicated deployment, or a model router) or an OHS-hosted agent config. `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. `progress` object optional Per-phase progress for a model evaluation run. The candidate phase invokes the candidate model once per dataset row; the judge phase scores each candidate-success row with the configured metrics. Counts grow as the run advances; compare against total_rows to render a progress bar. **Show child properties** `candidate_rows_evaluated` integer (int64) optional Example: `100` Dataset rows whose candidate model call has completed (success or failure). `judge_rows_evaluated` integer (int64) optional Example: `95` Candidate-success rows the judge has finished (scored or skipped). Caps at the number of candidate successes, which may be below total_rows. `total_rows` integer (int64) optional Example: `100` Total dataset rows for the run, sourced from the evaluation dataset. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "available_candidate_types": [ "CANDIDATE_MODEL_SOURCE_SERVERLESS" ], "available_statuses": [ "MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED" ], "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Model Evaluation Run `/v2/gen-ai/model_evaluation_runs` 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` `reasoning_effort` string optional Example: `low` Reasoning effort for reasoning-capable models (e.g. "low", "medium", "high"). Validated against the candidate model's supported values; a model that advertises none rejects this field. `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, CANDIDATE_MODEL_SOURCE_AGENT optional Example: `CANDIDATE_MODEL_SOURCE_SERVERLESS` Whether the candidate is a served model (serverless platform, a dedicated deployment, or a model router) or an OHS-hosted agent config. `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. `epochs` integer (int64) optional Example: `1` Number of times to evaluate each dataset row (n-pass/epochs), so the result reports avg@k/pass@k/cons@k instead of a single score. Defaults to 1 when unset. Capped at 3 until throughput/sharding work lands, since each extra epoch roughly multiplies wall-clock run time. Not persisted on presets. `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` `preset_save_sections` array of string (enum) optional Example: `["PRESET_SAVE_SECTION_CANDIDATE","PRESET_SAVE_SECTION_METRICS"]` Which sections of this run's resolved configuration to persist as a reusable preset. Each selected section saves only its own fields; the remaining sections stay empty on the preset and must be supplied inline on future runs that reference it. Empty means do not save a preset (unless the deprecated `save_as_preset` boolean is true, in which case all sections are saved). Ignored when `eval_preset_uuid` is set. Use `preset_name` to label the saved preset. `save_as_preset` boolean optional Example: `true` Deprecated: use `preset_save_sections`. When `true` and `preset_save_sections` is empty, all five sections of the resolved configuration are saved as a reusable preset (legacy behavior). Ignored when `eval_preset_uuid` is set. `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` ```json { "candidate_inference_config": { "max_tokens": 123, "reasoning_effort": "low", "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", "epochs": 1, "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", "preset_save_sections": [ "PRESET_SAVE_SECTION_CANDIDATE", "PRESET_SAVE_SECTION_METRICS" ], "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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "eval_run_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Model Evaluation Run `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `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` `candidate_routed_task` string optional Example: `Coding & brainstorming` `epoch` integer (int64) optional Example: `1` Which pass over this dataset row produced this result, 1-indexed (1 = first pass). Always 0 (and omitted from JSON) when the run's epochs is 1 (the default) — per-attempt epoch numbering doesn't apply to single-pass runs. When epochs > 1, this always reflects epoch 1 (see epoch_results below). `epoch_results` object optional Present only when the run's epochs > 1: every pass over this row — including epoch 1, duplicated here for convenience — keyed by 1-indexed "epoch1"/"epoch2"/"epoch3" labels. Mirrors the shape of the downloadable results file's epochResults object. The top-level fields above (output, metric_results, candidate_routed_task) always reflect epoch 1, so single-epoch clients reading only those fields see no difference when epochs > 1. **Show child properties** `(additional properties)` object optional Additional properties are allowed. `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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `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. `row_number` integer (int64) optional Example: `1` Which dataset row this result came from. Multiple results share a row_number when epochs > 1: one per pass over that row. `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` `reasoning_effort` string optional Example: `low` Reasoning effort for reasoning-capable models (e.g. "low", "medium", "high"). Validated against the candidate model's supported values; a model that advertises none rejects this field. `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, CANDIDATE_MODEL_SOURCE_AGENT optional Example: `CANDIDATE_MODEL_SOURCE_SERVERLESS` Whether the candidate is a served model (serverless platform, a dedicated deployment, or a model router) or an OHS-hosted agent config. `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. `epochs` integer (int64) optional Example: `1` Number of times each dataset row is evaluated (n-pass/epochs). 1 by default. Drives the avg@k/pass@k/cons@k aggregation in result_summary. `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** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. **Show child properties** `eval_preset_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique identifier of the saved model evaluation preset that references the metric. `name` string optional Example: `"My evaluation preset"` Display name of the saved model evaluation preset. `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `name` string optional Example: `example name` Name of the evaluation run. `progress` object optional Per-phase progress for a model evaluation run. The candidate phase invokes the candidate model once per dataset row; the judge phase scores each candidate-success row with the configured metrics. Counts grow as the run advances; compare against total_rows to render a progress bar. **Show child properties** `candidate_rows_evaluated` integer (int64) optional Example: `100` Dataset rows whose candidate model call has completed (success or failure). `judge_rows_evaluated` integer (int64) optional Example: `95` Candidate-success rows the judge has finished (scored or skipped). Caps at the number of candidate successes, which may be below total_rows. `total_rows` integer (int64) optional Example: `100` Total dataset rows for the run, sourced from the evaluation dataset. `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` `epoch_summary` object optional Aggregation across epochs when a run repeats each dataset row k times. Only populated when epochs > 1; at epochs == 1 every number here would equal overall_score_percent, so it is omitted rather than duplicated. **Show child properties** `avg_at_k_percent` number (double) optional Example: `123` Mean over rows of (passing epochs / scored epochs) for the star metric. Equals overall_score_percent; this is the primary result for a multi-epoch run ("how often does it work"). `cons_at_k_percent` number (double) optional Example: `123` Fraction of rows where a strict majority of scored epochs passed ("what does the model typically answer"). An even-k tie counts as fail. `epochs` integer (int64) optional Example: `123` Number of passes per dataset row (k). `pass_at_k_percent` number (double) optional Example: `123` Unbiased estimate of the probability that at least one of k epochs passes ("can it work at all, given retries"). Always the most generous of the three. `per_epoch` array of object optional Each epoch's own standalone score, persisted next to the aggregate. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `rows_excluded` integer (int64) optional Example: `123` Rows where every epoch failed or was skipped, so the row contributes to no score. Not a random sample of difficulty — surface this explicitly. `rows_scored` integer (int64) optional Example: `123` Rows with at least one scored epoch. The effective N behind every percentage above; always display alongside them. `score_stddev_percent` number (double) optional Example: `123` Population standard deviation of the k per-epoch scores below — the signal for whether a difference between runs is real or noise. `epochs` integer (int64) optional Example: `1` Number of times each dataset row was evaluated (n-pass/epochs). Mirrors ModelEvaluationRunDetail.epochs. 1 for every existing run. `metric_summaries` array of object optional Per-metric aggregated pass/fail statistics. **Show child properties** `avg_at_k_percent` number (double) optional Example: `123` Row-level (not attempt-level) aggregation across epochs for this metric, mirroring EpochResultSummary but scoped to one metric. Only set when the run's epochs > 1; pass_percent/pass_count/etc. above stay attempt-level (over row x epoch pairs) so they don't desynchronize from the counts sitting next to them. `cons_at_k_percent` number (double) optional Example: `123` `description` string optional Example: `example string` `fail_count` integer (int64) optional Example: `123` Rows where the metric failed to score or completed below the threshold. `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_at_k_percent` number (double) optional Example: `123` `pass_count` integer (int64) optional Example: `123` Rows where the metric completed and passed the configured threshold. `pass_percent` number (double) optional Example: `123` `skip_percent` number (double) optional Example: `123` Percentage of rows that were skipped for this metric, computed as skipped_count divided by the total rows the metric saw (pass_count + fail_count + skipped_count). `skipped_count` integer (int64) optional Example: `123` Rows where the metric was not evaluated for this prompt. `overall_score_percent` number (double) optional Example: `123` `per_model_summaries` object optional Per-model breakdown of an evaluation run. Set on router evaluations to show how each underlying model performed across the prompts that were routed to it. **Show child properties** `summaries` array of object optional One entry per underlying model that received at least one prompt during the evaluation run. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `per_task_summaries` object optional Per-task breakdown of an evaluation run. Set on router evaluations to show how each routing task category performed across the prompts that were classified into it. **Show child properties** `summaries` array of object optional One entry per routing task category that received at least one prompt during the evaluation run. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `token_usage` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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", "candidate_routed_task": "Coding \u0026 brainstorming", "epoch": 1, "ground_truth": "example string", "input": "example string", "metric_results": [], "output": "example string", "row_number": 1 } ], "run": { "candidate_inference_config": { "max_tokens": 123, "reasoning_effort": "low", "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", "epochs": 1, "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", "progress": { "candidate_rows_evaluated": 100, "judge_rows_evaluated": 95, "total_rows": 100 }, "result_summary": { "end_time": "2023-01-01T00:00:00Z", "epochs": 1, "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PATCH Update Model Evaluation Run `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}` To update a model evaluation run's display name, send a PATCH request to `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}`. #### Path Parameters `eval_run_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the model evaluation run to update. Returned by `CreateModelEvaluationRun` and listed via `ListModelEvaluationRuns`. #### Request Body: `application/json` `eval_run_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` UUID of the model evaluation run to update. Returned by `CreateModelEvaluationRun` and listed via `ListModelEvaluationRuns`. `name` string optional Example: `My evaluation run` Optional new display name for the evaluation run (max 255 characters). ##### Request: `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}` ### Payload Content type `application/json` ```json { "eval_run_uuid": "\"12345678-1234-1234-1234-123456789012\"", "name": "My evaluation run" } ``` ### cURL ```bash curl -X PATCH \ -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" \ -d '{ "name": "My new evaluation name" }' ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `run` object optional Model Evaluation Run Summary - lightweight view used in 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, CANDIDATE_MODEL_SOURCE_AGENT optional Example: `CANDIDATE_MODEL_SOURCE_SERVERLESS` Whether the candidate is a served model (serverless platform, a dedicated deployment, or a model router) or an OHS-hosted agent config. `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. `progress` object optional Per-phase progress for a model evaluation run. The candidate phase invokes the candidate model once per dataset row; the judge phase scores each candidate-success row with the configured metrics. Counts grow as the run advances; compare against total_rows to render a progress bar. **Show child properties** `candidate_rows_evaluated` integer (int64) optional Example: `100` Dataset rows whose candidate model call has completed (success or failure). `judge_rows_evaluated` integer (int64) optional Example: `95` Candidate-success rows the judge has finished (scored or skipped). Caps at the number of candidate successes, which may be below total_rows. `total_rows` integer (int64) optional Example: `100` Total dataset rows for the run, sourced from the evaluation dataset. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "run": { "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", "progress": { "candidate_rows_evaluated": 100, "judge_rows_evaluated": 95, "total_rows": 100 }, "status": "MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Model Evaluation Run `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "error": "example string", "status": "DELETE_MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Cancel Model Evaluation Run `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}/cancel` To cancel an in-progress model evaluation run, send a PUT request to `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}/cancel`. #### Path Parameters `eval_run_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the model evaluation run to cancel. Returned by `CreateModelEvaluationRun` and listed via `ListModelEvaluationRuns`. The run must be in a non-terminal status (queued, running_dataset, or evaluating_results); already-terminal runs return an error. #### Request Body: `application/json` `eval_run_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` UUID of the model evaluation run to cancel. Returned by `CreateModelEvaluationRun` and listed via `ListModelEvaluationRuns`. The run must be in a non-terminal status (queued, running_dataset, or evaluating_results); already-terminal runs return an error. ##### Request: `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}/cancel` ### Payload Content type `application/json` ```json { "eval_run_uuid": "\"12345678-1234-1234-1234-123456789012\"" } ``` ### cURL ```bash curl -X PUT \ -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/cancel" \ -d '{ "eval_run_uuid": "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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `run` object optional Model Evaluation Run Summary - lightweight view used in 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, CANDIDATE_MODEL_SOURCE_AGENT optional Example: `CANDIDATE_MODEL_SOURCE_SERVERLESS` Whether the candidate is a served model (serverless platform, a dedicated deployment, or a model router) or an OHS-hosted agent config. `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. `progress` object optional Per-phase progress for a model evaluation run. The candidate phase invokes the candidate model once per dataset row; the judge phase scores each candidate-success row with the configured metrics. Counts grow as the run advances; compare against total_rows to render a progress bar. **Show child properties** `candidate_rows_evaluated` integer (int64) optional Example: `100` Dataset rows whose candidate model call has completed (success or failure). `judge_rows_evaluated` integer (int64) optional Example: `95` Candidate-success rows the judge has finished (scored or skipped). Caps at the number of candidate successes, which may be below total_rows. `total_rows` integer (int64) optional Example: `100` Total dataset rows for the run, sourced from the evaluation dataset. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "run": { "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", "progress": { "candidate_rows_evaluated": 100, "judge_rows_evaluated": 95, "total_rows": 100 }, "status": "MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "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` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "download_url": "example string", "expires_at": "2023-01-01T00:00:00Z" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Available Models `/v2/gen-ai/models` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/models" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `models` array of object optional The models **Show child properties** `agreement` object optional Agreement Description **Show child properties** `description` string optional Example: `example string` `name` string optional Example: `example name` `url` string optional Example: `example string` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `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** `cache_read_input_price_per_million` number (double) optional Example: `0.15` Per-million cache read rate for standard chat models (token_type "cache read input"). Multimodal models use text_cache_read_input_price_per_million / image_cache_read_input_price_per_million instead. `cache_write_1h_input_price_per_million` number (double) optional Example: `10` Price per million tokens written to the prompt cache with a 1-hour lifetime. `cache_write_5m_input_price_per_million` number (double) optional Example: `6.25` Price per million tokens written to the prompt cache with a 5-minute lifetime. `image_cache_read_input_price_per_million` number (double) optional Example: `0.08` `image_input_price_per_million` number (double) optional Example: `0.3` `image_output_price_per_million` number (double) optional Example: `0.4` `input_cache_read` number (double) optional Example: `0.15` Cache read input price per single token. Equivalent to cache_read_input_price_per_million. `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` `reasoning_price_per_million` number (double) optional Example: `0` Price per million reasoning tokens. 0 if the model does not charge separately for reasoning tokens. `text_cache_read_input_price_per_million` number (double) optional Example: `0.05` `text_input_price_per_million` number (double) optional Example: `0.1` Per-million token rates for models that bill text vs image tokens separately (e.g. OpenAI gpt-image-2). Standard chat models leave these at 0 and use input_price_per_million / output_price_per_million instead. Values align with usage token_type / internal/usage.Type string values for each meter. `text_output_price_per_million` number (double) optional Example: `0.2` `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Model API Keys `/v2/gen-ai/models/api_keys` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/models/api_keys" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_infos` array of object optional Api key infos **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date `created_by` string (uint64) optional Example: `12345` Created by `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted date `name` string optional Example: `example name` Name `secret_key` string optional Example: `example string` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create a Model API Key Deprecated `/v2/gen-ai/models/api_keys` **Note: This endpoint is deprecated and has been retired. All requests return a `410 gone` response.** Creating model API keys through this endpoint is no longer supported. To create a model access key, visit the manage page in the control panel. Previously, you could create a model API key by sending 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` ```json { "name": "Production Key" } ``` ### cURL ```bash curl -X POST \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Production Key" }' \ "https://api.digitalocean.com/v2/gen-ai/models/api_keys" ``` #### Responses **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **410** The endpoint has been retired. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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 **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **410** ```json { "id": "gone", "message": "resource retired: Creating model API keys through this endpoint is retired. Go to manage page in the control panel to create a model access key." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update API Key for a Model `/v2/gen-ai/models/api_keys/{api_key_uuid}` 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` ```json { "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"", "name": "\"Production Key\"" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/models/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \ -d '{ "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4", "name": "test-key2" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Model API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date `created_by` string (uint64) optional Example: `12345` Created by `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted date `name` string optional Example: `example name` Name `secret_key` string optional Example: `example string` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete API Key for a Model `/v2/gen-ai/models/api_keys/{api_key_uuid}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/models/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Model API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date `created_by` string (uint64) optional Example: `12345` Created by `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted date `name` string optional Example: `example name` Name `secret_key` string optional Example: `example string` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Regenerate API Key for a Model `/v2/gen-ai/models/api_keys/{api_key_uuid}/regenerate` 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 ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/models/api_keys/11efcf7e-824d-2808-bf8f-4e013e2ddde4/regenerate" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `api_key_info` object optional Model API Key Info **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Creation date `created_by` string (uint64) optional Example: `12345` Created by `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted date `name` string optional Example: `example name` Name `secret_key` string optional Example: `example string` `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Uuid **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Model Catalog `/v2/gen-ai/models/catalog` Returns all available models. #### Query Parameters `page` integer optional Example: `1` Page number for pagination. `limit` integer optional Example: `1` Deprecated. Use `per_page` instead. `search` string optional Example: `llama` Partial, case-insensitive match on the model's display name. `model_type` array of string optional Example: `["chat"]` Filter by model type. Multiple values use OR semantics. Accepted values: `chat`, `embedding`, `image`, `reasoning`, `coding`, `audio`, `reranking`. `provider` array of string optional Example: `["Meta"]` Filter by model creator/developer. Multiple values use OR semantics. Values are data-driven; use `available_providers` from the response to discover valid options. `availability` array of string optional Example: `["serverless"]` Filter by deployment availability. Multiple values use OR semantics. Accepted values: `serverless`, `dedicated`. `badges` array of string optional Example: `["featured"]` Filter by badge. Multiple values use OR semantics. Accepted values: `featured`, `new`, `preview`. `sort_by` string, one of: MODEL_CATALOG_SORT_BY_CREATED_AT, MODEL_CATALOG_SORT_BY_NAME, MODEL_CATALOG_SORT_BY_PRICE optional Example: `MODEL_CATALOG_SORT_BY_NAME` Field to sort results by. Default is `MODEL_CATALOG_SORT_BY_CREATED_AT`. - MODEL_CATALOG_SORT_BY_CREATED_AT: Default: sort by creation date. - MODEL_CATALOG_SORT_BY_NAME: Sort by the model's display name (case-insensitive). - MODEL_CATALOG_SORT_BY_PRICE: Sort by input token price. Default: `MODEL_CATALOG_SORT_BY_CREATED_AT` `per_page` integer optional Example: `1` Number of items per page. Replaces the deprecated `limit` field. `sort_direction` string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Example: `SORT_DIRECTION_ASC` Sort direction. Defaults to descending when unspecified. Default: `SORT_DIRECTION_UNSPECIFIED` `use_case` string (enum) optional Example: `MODEL_CATALOG_USE_CASE_CODING` Filter by pre-defined use case. When unspecified, no use-case filter is applied. Accepted values: `MODEL_CATALOG_USE_CASE_CODING`, `MODEL_CATALOG_USE_CASE_AGENTS`, `MODEL_CATALOG_USE_CASE_AUDIO`, `MODEL_CATALOG_USE_CASE_IMAGE`, `MODEL_CATALOG_USE_CASE_EMBEDDING`, `MODEL_CATALOG_USE_CASE_VIDEO`. - MODEL_CATALOG_USE_CASE_UNSPECIFIED: No use-case filter applied; return all models. - MODEL_CATALOG_USE_CASE_CODING: Coding-optimized models: model_type = coding, or usecases include coding, agentic_coding, or code_generation. - MODEL_CATALOG_USE_CASE_AGENTS: Agent-building models: usecases include tool_calling, agentic, agent_platform, agentic_workflows, or agentic_coding. - MODEL_CATALOG_USE_CASE_AUDIO: Audio models: model_type is audio, or usecases include audio, text_to_speech, or voice_cloning, or output modalities include audio. - MODEL_CATALOG_USE_CASE_IMAGE: Image models: model_type is image, or usecases include image_generation, text_to_image, or ideogram, or output modalities include image. - MODEL_CATALOG_USE_CASE_VIDEO: Video models: usecases include video_generation or text_to_video, or output modalities include video. - MODEL_CATALOG_USE_CASE_EMBEDDING: Embedding and reranking models: model_type is embedding or reranking, or usecases include vectorization or reranking. Default: `MODEL_CATALOG_USE_CASE_UNSPECIFIED` ##### Request: `/v2/gen-ai/models/catalog` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/models/catalog?page=1&per_page=20&search=llama&model_type=chat&sort_by=MODEL_CATALOG_SORT_BY_NAME&sort_direction=SORT_DIRECTION_ASC" ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `available_availability` array of string optional Example: `["example string"]` All deployment availability values the client can offer in the availability filter UI. `available_badges` array of string optional Example: `["example string"]` All badge values the client can offer in the badges filter UI. `available_model_types` array of string optional Example: `["example string"]` All model type values the client can offer in the type filter UI. `available_providers` array of string optional Example: `["example string"]` All provider values the client can offer in the provider filter UI. `available_sort_by` array of string, one of: MODEL_CATALOG_SORT_BY_CREATED_AT, MODEL_CATALOG_SORT_BY_NAME, MODEL_CATALOG_SORT_BY_PRICE optional All sort-by field values the client can offer in the sort UI. `available_sort_directions` array of string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional All sort-direction values the client can offer in the sort UI. `data` array of object optional **Show child properties** `availability` array of string optional Example: `["example string"]` `badges` array of string optional Example: `["example string"]` Badges for models `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) `created_at` string (date-time) optional Example: `2021-01-01T00:00:00Z` RFC 3339 timestamp indicating when the model was added to the catalog. `creator` string optional Example: `"Meta"` Model creator/developer (e.g., "Meta", "Anthropic", "OpenAI") `hugging_face_id` string optional Example: `"meta-llama/Llama-3.3-70B-Instruct"` The Hugging Face repository ID (e.g. "meta-llama/Llama-3.3-70B-Instruct") the model is based on, when applicable. Omitted for models not sourced from Hugging Face. `id` string optional Example: `"506a3371-88d0-4047-9212-e2079497ac68"` Identity `max_output_tokens` string (int64) optional Example: `65536` The maximum number of output tokens the model can generate in a single response. `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** `cache_read_input_price_per_million` number (double) optional Example: `0.15` Per-million cache read rate for standard chat models (token_type "cache read input"). Multimodal models use text_cache_read_input_price_per_million / image_cache_read_input_price_per_million instead. `cache_write_1h_input_price_per_million` number (double) optional Example: `10` Price per million tokens written to the prompt cache with a 1-hour lifetime. `cache_write_5m_input_price_per_million` number (double) optional Example: `6.25` Price per million tokens written to the prompt cache with a 5-minute lifetime. `image_cache_read_input_price_per_million` number (double) optional Example: `0.08` `image_input_price_per_million` number (double) optional Example: `0.3` `image_output_price_per_million` number (double) optional Example: `0.4` `input_cache_read` number (double) optional Example: `0.15` Cache read input price per single token. Equivalent to cache_read_input_price_per_million. `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` `reasoning_price_per_million` number (double) optional Example: `0` Price per million reasoning tokens. 0 if the model does not charge separately for reasoning tokens. `text_cache_read_input_price_per_million` number (double) optional Example: `0.05` `text_input_price_per_million` number (double) optional Example: `0.1` Per-million token rates for models that bill text vs image tokens separately (e.g. OpenAI gpt-image-2). Standard chat models leave these at 0 and use input_price_per_million / output_price_per_million instead. Values align with usage token_type / internal/usage.Type string values for each meter. `text_output_price_per_million` number (double) optional Example: `0.2` `provider` string, one of: MODEL_PROVIDER_DIGITALOCEAN, MODEL_PROVIDER_ANTHROPIC, MODEL_PROVIDER_OPENAI optional Example: `MODEL_PROVIDER_DIGITALOCEAN` `scaled_pricing_enabled` boolean optional Example: `true` True when this model's pricing varies over time. Retrieve the model's details for the full pricing schedule. False for models with fixed pricing. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "available_availability": [ "example string" ], "available_badges": [ "example string" ], "available_model_types": [ "example string" ], "available_providers": [ "example string" ], "available_sort_by": [ "MODEL_CATALOG_SORT_BY_CREATED_AT" ], "available_sort_directions": [ "SORT_DIRECTION_UNSPECIFIED" ], "data": [ { "availability": [ "example string" ], "badges": [ "example string" ], "capabilities": [ "example string" ], "context_window": "128000", "created_at": "2021-01-01T00:00:00Z", "creator": "\"Meta\"", "hugging_face_id": "\"meta-llama/Llama-3.3-70B-Instruct\"", "id": "\"506a3371-88d0-4047-9212-e2079497ac68\"", "max_output_tokens": "65536", "model_id": "\"llama3.1-70b-instruct\"", "name": "\"Llama 3.1 70B\"", "parameter_count": 70, "provider": "MODEL_PROVIDER_DIGITALOCEAN", "scaled_pricing_enabled": true, "short_description": "\"Fast, efficient model for general tasks\"", "type": "\"text-to-text\"" } ], "meta": { "page": 123, "pages": 123, "total": 123 } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get Model Catalog Card `/v2/gen-ai/models/catalog/{id}` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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"]` `badges` array of string optional Example: `["example string"]` Badges for models `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 `hugging_face_id` string optional Example: `"meta-llama/Llama-3.3-70B-Instruct"` The Hugging Face repository ID (e.g. "meta-llama/Llama-3.3-70B-Instruct") the model is based on, when applicable. Omitted for models not sourced from Hugging Face. `id` string optional Example: `"506a3371-88d0-4047-9212-e2079497ac68"` Identity (same as Entry) `max_output_tokens` string (int64) optional Example: `65536` The maximum number of output tokens the model can generate in a single response. `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** `cache_read_input_price_per_million` number (double) optional Example: `0.15` Per-million cache read rate for standard chat models (token_type "cache read input"). Multimodal models use text_cache_read_input_price_per_million / image_cache_read_input_price_per_million instead. `cache_write_1h_input_price_per_million` number (double) optional Example: `10` Price per million tokens written to the prompt cache with a 1-hour lifetime. `cache_write_5m_input_price_per_million` number (double) optional Example: `6.25` Price per million tokens written to the prompt cache with a 5-minute lifetime. `image_cache_read_input_price_per_million` number (double) optional Example: `0.08` `image_input_price_per_million` number (double) optional Example: `0.3` `image_output_price_per_million` number (double) optional Example: `0.4` `input_cache_read` number (double) optional Example: `0.15` Cache read input price per single token. Equivalent to cache_read_input_price_per_million. `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` `reasoning_price_per_million` number (double) optional Example: `0` Price per million reasoning tokens. 0 if the model does not charge separately for reasoning tokens. `text_cache_read_input_price_per_million` number (double) optional Example: `0.05` `text_input_price_per_million` number (double) optional Example: `0.1` Per-million token rates for models that bill text vs image tokens separately (e.g. OpenAI gpt-image-2). Standard chat models leave these at 0 and use input_price_per_million / output_price_per_million instead. Values align with usage token_type / internal/usage.Type string values for each meter. `text_output_price_per_million` number (double) optional Example: `0.2` `pricing_detail` object optional The complete set of prices for a model, covering every available variant. **Show child properties** `variants` array of object optional Each available pricing variant for the model. **Show child properties** `currency` string optional Example: `USD` Currency code for this variant's rates (e.g. `USD`). `label` string optional Example: `Standard` Display name for the variant (e.g. `Standard`, `Fast Mode`, `1M Context`). `mode` string, one of: MODEL_BILLING_MODE_UNSPECIFIED, MODEL_BILLING_MODE_INTERACTIVE, MODEL_BILLING_MODE_BATCH optional Example: `MODEL_BILLING_MODE_UNSPECIFIED` Whether rates apply to real-time or batch requests. - MODEL_BILLING_MODE_INTERACTIVE: Real-time request pricing. - MODEL_BILLING_MODE_BATCH: Discounted pricing for asynchronous batch requests. `prices` object optional Pricing per million tokens (aligns with existing ModelPrice pattern) *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `scaled_pricing` object optional Pricing that varies over time. When present, the rates move between the low and high bounds below across the intervals in the schedule. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `tier` string (enum) optional Example: `MODEL_PRICING_TIER_UNSPECIFIED` A pricing variant of a model, such as a faster serving option or a larger context window. - MODEL_PRICING_TIER_STANDARD: Default pricing. - MODEL_PRICING_TIER_FAST_MODE: Faster, higher-priority serving at a premium price. - MODEL_PRICING_TIER_EXTENDED_1M: Pricing for the 1M-token context window. - MODEL_PRICING_TIER_EXTENDED_272K: Pricing for the 272K-token context window. - MODEL_PRICING_TIER_BYOK: Pricing when using your own model API key. `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "data": { "availability": [ "example string" ], "badges": [ "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...\"", "hugging_face_id": "\"meta-llama/Llama-3.3-70B-Instruct\"", "id": "\"506a3371-88d0-4047-9212-e2079497ac68\"", "max_output_tokens": "65536", "modalities": { "input": [ "example string" ], "output": [ "example string" ] }, "model_id": "\"llama3.1-70b-instruct\"", "name": "\"Llama 3.1 70B\"", "parameter_count": 70, "pricing": { "cache_read_input_price_per_million": 0.15, "cache_write_1h_input_price_per_million": 10, "cache_write_5m_input_price_per_million": 6.25, "image_cache_read_input_price_per_million": 0.08, "image_input_price_per_million": 0.3, "image_output_price_per_million": 0.4, "input_cache_read": 0.15, "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, "reasoning_price_per_million": 0, "text_cache_read_input_price_per_million": 0.05, "text_input_price_per_million": 0.1, "text_output_price_per_million": 0.2 }, "pricing_detail": { "variants": [] }, "provider": "MODEL_PROVIDER_DIGITALOCEAN", "short_description": "\"Fast, efficient model for general tasks\"", "type": "\"text-to-text\"" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Model Routers `/v2/gen-ai/models/routers` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create a Model Router `/v2/gen-ai/models/routers` 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"]` At least one fallback model is required; order defines failover priority `name` string optional Example: `"my-model-router"` Model router name: lowercase, at most 255 characters, only a-z, 0-9, and hyphens `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"]` DEPRECATED: this field does not affect deployment and model routers are always deployed to all regions. Must be omitted or set to \["all"]. ##### Request: `/v2/gen-ai/models/routers` ### Payload Content type `application/json` ```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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Model Router Presets `/v2/gen-ai/models/routers/presets` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Model Router Task Presets `/v2/gen-ai/models/routers/tasks/presets` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve an Existing Model Router `/v2/gen-ai/models/routers/{uuid}` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update a Model Router `/v2/gen-ai/models/routers/{uuid}` 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: lowercase, at most 255 characters, only a-z, 0-9, and hyphens `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"]` DEPRECATED: this field does not affect deployment and model routers are always deployed to all regions. Must be omitted or set to \["all"]. `uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Model router id ##### Request: `/v2/gen-ai/models/routers/{uuid}` ### Payload Content type `application/json` ```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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete a Model Router `/v2/gen-ai/models/routers/{uuid}` 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 ```bash 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Get Oauth2 Dropbox Tokens `/v2/gen-ai/oauth2/dropbox/tokens` 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` ```json { "code": "example string", "redirect_url": "example string" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/oauth2/dropbox/tokens?code=" ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `refresh_token` string optional Example: `example string` The refresh token `token` string optional Example: `example string` The access token **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "refresh_token": "example string", "token": "example string" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get Oauth2 URL `/v2/gen-ai/oauth2/url` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/oauth2/url?type=google&redirect_uri=http://localhost:3000" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `url` string optional Example: `example string` The oauth2 url **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "url": "example string" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List OpenAI API Keys `/v2/gen-ai/openai/keys` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/openai/keys" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create OpenAI API Key `/v2/gen-ai/openai/keys` 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` ```json { "api_key": "\"sk-proj--123456789098765432123456789\"", "name": "\"Production Key\"" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/openai/keys" \ -d '{ "api_key": "sk-proj--12345678901234567890123456789012", "name": "test-key" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get OpenAI API Key `/v2/gen-ai/openai/keys/{api_key_uuid}` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update OpenAI API Key `/v2/gen-ai/openai/keys/{api_key_uuid}` 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` ```json { "api_key": "\"sk-ant-12345678901234567890123456789012\"", "api_key_uuid": "\"12345678-1234-1234-1234-123456789012\"", "name": "\"Production Key\"" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \ -d '{ "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4", "name": "test-key2" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete OpenAI API Key `/v2/gen-ai/openai/keys/{api_key_uuid}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List agents by OpenAI key `/v2/gen-ai/openai/keys/{uuid}/agents` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/agents" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true } ], "links": { "pages": { "first": "example string", "last": "example string", "next": "example string", "previous": "example string" } }, "meta": { "page": 123, "pages": 123, "total": 123 } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Datacenter Regions `/v2/gen-ai/regions` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/regions" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `regions` array of object optional Region code **Show child properties** `inference_url` string optional Example: `example string` Url for inference server `region` string optional Example: `example string` Region code `serves_batch` boolean optional Example: `true` This datacenter is capable of running batch jobs `serves_inference` boolean optional Example: `true` This datacenter is capable of serving inference `stream_inference_url` string optional Example: `example string` The url for the inference streaming server **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "regions": [ { "inference_url": "example string", "region": "example string", "serves_batch": true, "serves_inference": true, "stream_inference_url": "example string" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Common Scenario & Goal Library `/v2/gen-ai/scenario_library` To list the platform-curated Common Scenario & Goal Library, send a GET request to `/v2/gen-ai/scenario_library`. #### Query Parameters `page` integer optional Example: `1` Page number. `per_page` integer optional Example: `1` Items per page. `category` string optional Example: `example string` Filter by category (exact match). Empty means no category filter. `search` string optional Example: `example string` Free-text search across name, description, and goal_description (case-insensitive substring match). Empty means no search. `sort_by` string, one of: SCENARIO_LIBRARY_SORT_FIELD_UNSPECIFIED, SCENARIO_LIBRARY_SORT_FIELD_NAME, SCENARIO_LIBRARY_SORT_FIELD_CREATED_AT optional Example: `SCENARIO_LIBRARY_SORT_FIELD_UNSPECIFIED` Field to sort by. Defaults to name when unspecified. - SCENARIO_LIBRARY_SORT_FIELD_NAME: Sort by customer-facing name (case-insensitive). Default. - SCENARIO_LIBRARY_SORT_FIELD_CREATED_AT: Sort by creation date. Default: `SCENARIO_LIBRARY_SORT_FIELD_UNSPECIFIED` `sort_direction` string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Example: `SORT_DIRECTION_UNSPECIFIED` Sort direction. Defaults to ascending when unspecified. Default: `SORT_DIRECTION_UNSPECIFIED` ##### Request: `/v2/gen-ai/scenario_library` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_library" ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `available_categories` array of string optional Example: `["example string"]` Categories currently in use, for filtering library results. `available_sort_by` array of string, one of: SCENARIO_LIBRARY_SORT_FIELD_UNSPECIFIED, SCENARIO_LIBRARY_SORT_FIELD_NAME, SCENARIO_LIBRARY_SORT_FIELD_CREATED_AT optional Sort-by values available for this list request. `available_sort_directions` array of string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Sort-direction values available for this list request. `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `scenarios` array of object optional The library entries for the current page. **Show child properties** `category` string optional Example: `example string` Optional grouping for catalog browsing (e.g. "Billing", "Onboarding"). Empty when uncategorized. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `description` string optional Example: `example string` Curated description. `goal_description` string optional Example: `example string` The goal this scenario set demonstrates, shown as context alongside goal-driven generation. `library_scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the library entry. `name` string optional Example: `example name` Curated display name. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the library entry. `status` string, one of: SCENARIO_LIBRARY_ENTRY_STATUS_UNSPECIFIED, SCENARIO_LIBRARY_ENTRY_STATUS_ACTIVE, SCENARIO_LIBRARY_ENTRY_STATUS_ARCHIVED optional Example: `SCENARIO_LIBRARY_ENTRY_STATUS_UNSPECIFIED` Lifecycle status of a Common Scenario & Goal Library entry. - SCENARIO_LIBRARY_ENTRY_STATUS_ACTIVE: Visible in the library and available to copy into a scenario set. - SCENARIO_LIBRARY_ENTRY_STATUS_ARCHIVED: Hidden from the library catalog. Existing scenario sets created from this entry keep their provenance. `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "available_categories": [ "example string" ], "available_sort_by": [ "SCENARIO_LIBRARY_SORT_FIELD_UNSPECIFIED" ], "available_sort_directions": [ "SORT_DIRECTION_UNSPECIFIED" ], "links": { "pages": { "first": "example string", "last": "example string", "next": "example string", "previous": "example string" } }, "meta": { "page": 123, "pages": 123, "total": 123 }, "scenarios": [ { "category": "example string", "created_at": "2023-01-01T00:00:00Z", "description": "example string", "goal_description": "example string", "library_scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name", "scenario_count": 123, "status": "SCENARIO_LIBRARY_ENTRY_STATUS_UNSPECIFIED", "updated_at": "2023-01-01T00:00:00Z" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Scenario Set From Library `/v2/gen-ai/scenario_library/{library_scenario_uuid}/create_scenario_set` To create a scenario set from a Common Scenario & Goal Library entry, send a POST request to `/v2/gen-ai/scenario_library/{library_scenario_uuid}/create_scenario_set`. The library scenarios are copied into a new scenario set owned by the calling team. The new set is ready to use when creating a simulation run. #### Path Parameters `library_scenario_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the library entry to copy. #### Request Body: `application/json` `library_scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the library entry to copy. `name` string optional Example: `example name` Optional name for the new scenario set. Defaults to the library entry's name when unset. ##### Request: `/v2/gen-ai/scenario_library/{library_scenario_uuid}/create_scenario_set` ### Payload Content type `application/json` ```json { "library_scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_library/12345678-1234-1234-1234-123456789012/create_scenario_set" \ -d '{ "library_scenario_uuid": "12345678-1234-1234-1234-123456789012", "name": "Billing Refund Escalation" }' ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `scenario_set` object optional A team-owned collection of scenarios. **Show child properties** `bucket_name` string optional Example: `example name` Object storage bucket holding the scenario file. Unset while status is generating. `bucket_region` string optional Example: `example string` Object storage bucket region. Unset while status is generating. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the scenario set has been deleted. `description` string optional Example: `example string` Customer-supplied description. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `generator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model that produced the scenarios. Only set for goal-generated scenario sets. `library_scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the source library entry. Only set for library scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_LIBRARY`). `name` string optional Example: `example name` Customer-supplied name. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the set. Unset while status is generating. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set. `source_export_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Signals export UUID that produced this set. Only set for signal-generated scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED`). `source_goal_description` string optional Example: `example string` The goal that drove generation. Only set for goal_generated scenario sets. `source_kind` string, one of: SCENARIO_SET_SOURCE_KIND_UNSPECIFIED, SCENARIO_SET_SOURCE_KIND_USER_UPLOAD, SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED, SCENARIO_SET_SOURCE_KIND_LIBRARY, SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED optional Example: `SCENARIO_SET_SOURCE_KIND_UNSPECIFIED` How a scenario set was created. - SCENARIO_SET_SOURCE_KIND_USER_UPLOAD: Created from uploaded or inline scenarios. - SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED: Produced by goal-driven generation. - SCENARIO_SET_SOURCE_KIND_LIBRARY: Copied from a platform-curated library entry. - SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED: Produced from a completed Signals export. `spaces_key` string optional Example: `example string` Object storage key for the scenario file. Unset while status is generating. `status` string, one of: SCENARIO_SET_STATUS_UNSPECIFIED, SCENARIO_SET_STATUS_GENERATING, SCENARIO_SET_STATUS_READY, SCENARIO_SET_STATUS_FAILED, SCENARIO_SET_STATUS_CANCELLED optional Example: `SCENARIO_SET_STATUS_UNSPECIFIED` Lifecycle status of a scenario set. Uploaded sets are created as ready. Generated sets start as generating and then become ready, failed, or cancelled. - SCENARIO_SET_STATUS_GENERATING: Generation is in progress. The scenarios are not ready yet. - SCENARIO_SET_STATUS_READY: The scenario set is ready to use. - SCENARIO_SET_STATUS_FAILED: Generation failed. The scenario set has no readable scenarios. - SCENARIO_SET_STATUS_CANCELLED: Generation was cancelled before completion. `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the generation workflow. Only set for goal-generated scenario sets. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "scenario_set": { "bucket_name": "example name", "bucket_region": "example string", "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "description": "example string", "failure_reason": "example string", "generator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "library_scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "source_export_id": "123e4567-e89b-12d3-a456-426614174000", "source_goal_description": "example string", "source_kind": "SCENARIO_SET_SOURCE_KIND_UNSPECIFIED", "spaces_key": "example string", "status": "SCENARIO_SET_STATUS_UNSPECIFIED", "updated_at": "2023-01-01T00:00:00Z", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Scenarios In Library Entry `/v2/gen-ai/scenario_library/{library_scenario_uuid}/scenarios` To list the scenarios inside a Common Scenario & Goal Library entry without creating a team-owned scenario set, send a GET request to `/v2/gen-ai/scenario_library/{library_scenario_uuid}/scenarios`. #### Path Parameters `library_scenario_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the library entry to read. #### Query Parameters `page` integer optional Example: `1` Page number. `per_page` integer optional Example: `1` Items per page. `search` string optional Example: `example string` Free-text search across name, description, and user_persona (case-insensitive substring match). Empty means no search. `sort_by` string, one of: SCENARIO_SORT_FIELD_UNSPECIFIED, SCENARIO_SORT_FIELD_FILE_ORDER, SCENARIO_SORT_FIELD_NAME, SCENARIO_SORT_FIELD_DESCRIPTION optional Example: `SCENARIO_SORT_FIELD_UNSPECIFIED` Field to sort by. Defaults to original file order when unspecified. - SCENARIO_SORT_FIELD_FILE_ORDER: Preserve original file order. Default. - SCENARIO_SORT_FIELD_NAME: Sort by scenario name (case-insensitive). Empty names sort last. - SCENARIO_SORT_FIELD_DESCRIPTION: Sort by scenario description (case-insensitive). Default: `SCENARIO_SORT_FIELD_UNSPECIFIED` `sort_direction` string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Example: `SORT_DIRECTION_UNSPECIFIED` Sort direction. Defaults to ascending when unspecified. Default: `SORT_DIRECTION_UNSPECIFIED` ##### Request: `/v2/gen-ai/scenario_library/{library_scenario_uuid}/scenarios` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_library/12345678-1234-1234-1234-123456789012/scenarios" ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `available_sort_by` array of string, one of: SCENARIO_SORT_FIELD_UNSPECIFIED, SCENARIO_SORT_FIELD_FILE_ORDER, SCENARIO_SORT_FIELD_NAME, SCENARIO_SORT_FIELD_DESCRIPTION optional Sort-by values available for this list request. `available_sort_directions` array of string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Sort-direction values available for this list request. `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `scenarios` array of object optional The scenarios for the current page. **Show child properties** `description` string optional Example: `example string` What the user tries to accomplish. Required. `exploration_budget` integer (int64) optional Example: `123` Number of journeys to explore for this scenario. Defaults to 1 if unset. `max_turns` integer (int64) optional Example: `123` Turn budget for the scenario. Falls back to the run-level default if unset. `name` string optional Example: `example name` Human-readable name for the scenario. Optional. `scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id for the scenario. Always generated by the API; any customer-supplied value is ignored and overwritten. `stopping_criteria` array of string optional Example: `["example string"]` Judge stopping criteria. Required; must contain at least one entry. `user_persona` string optional Example: `example string` How the user communicates (tone, role). Optional. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "available_sort_by": [ "SCENARIO_SORT_FIELD_UNSPECIFIED" ], "available_sort_directions": [ "SORT_DIRECTION_UNSPECIFIED" ], "links": { "pages": { "first": "example string", "last": "example string", "next": "example string", "previous": "example string" } }, "meta": { "page": 123, "pages": 123, "total": 123 }, "scenarios": [ { "description": "example string", "exploration_budget": 123, "max_turns": 123, "name": "example name", "scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "stopping_criteria": [ "example string" ], "user_persona": "example string" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Scenario Sets `/v2/gen-ai/scenario_sets` To list scenario sets, send a GET request to `/v2/gen-ai/scenario_sets`. #### Query Parameters `page` integer optional Example: `1` Page number. `per_page` integer optional Example: `1` Items per page. `statuses` array of string, one of: SCENARIO_SET_STATUS_UNSPECIFIED, SCENARIO_SET_STATUS_GENERATING, SCENARIO_SET_STATUS_READY, SCENARIO_SET_STATUS_FAILED, SCENARIO_SET_STATUS_CANCELLED optional Example: `["SCENARIO_SET_STATUS_READY"]` Filter by one or more statuses. Empty means no status filter. - SCENARIO_SET_STATUS_GENERATING: Generation is in progress. The scenarios are not ready yet. - SCENARIO_SET_STATUS_READY: The scenario set is ready to use. - SCENARIO_SET_STATUS_FAILED: Generation failed. The scenario set has no readable scenarios. - SCENARIO_SET_STATUS_CANCELLED: Generation was cancelled before completion. `source_kinds` array of string, one of: SCENARIO_SET_SOURCE_KIND_UNSPECIFIED, SCENARIO_SET_SOURCE_KIND_USER_UPLOAD, SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED, SCENARIO_SET_SOURCE_KIND_LIBRARY, SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED optional Example: `["SCENARIO_SET_SOURCE_KIND_USER_UPLOAD"]` Filter by one or more source kinds. Empty means no source-kind filter. - SCENARIO_SET_SOURCE_KIND_USER_UPLOAD: Created from uploaded or inline scenarios. - SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED: Produced by goal-driven generation. - SCENARIO_SET_SOURCE_KIND_LIBRARY: Copied from a platform-curated library entry. - SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED: Produced from a completed Signals export. `search` string optional Example: `example string` Free-text search across name and description (case-insensitive substring match). Empty means no search. `sort_by` string (enum) optional Example: `SCENARIO_SET_SORT_FIELD_UNSPECIFIED` Field to sort by. Defaults to creation date when unspecified. - SCENARIO_SET_SORT_FIELD_CREATED_AT: Sort by creation date. Default. - SCENARIO_SET_SORT_FIELD_NAME: Sort by customer-supplied name (case-insensitive). - SCENARIO_SET_SORT_FIELD_STATUS: Sort by status using lifecycle order (generating → ready → terminal). - SCENARIO_SET_SORT_FIELD_SCENARIO_COUNT: Sort by scenario_count. - SCENARIO_SET_SORT_FIELD_UPDATED_AT: Sort by last update date. Default: `SCENARIO_SET_SORT_FIELD_UNSPECIFIED` `sort_direction` string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Example: `SORT_DIRECTION_UNSPECIFIED` Sort direction. Defaults to descending when unspecified. Default: `SORT_DIRECTION_UNSPECIFIED` ##### Request: `/v2/gen-ai/scenario_sets` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_sets" ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `available_sort_by` array of string (enum) optional Sort-by values available for this list request. `available_sort_directions` array of string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Sort-direction values available for this list request. `available_source_kinds` array of string, one of: SCENARIO_SET_SOURCE_KIND_UNSPECIFIED, SCENARIO_SET_SOURCE_KIND_USER_UPLOAD, SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED, SCENARIO_SET_SOURCE_KIND_LIBRARY, SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED optional Source kinds available for filtering this list request. `available_statuses` array of string, one of: SCENARIO_SET_STATUS_UNSPECIFIED, SCENARIO_SET_STATUS_GENERATING, SCENARIO_SET_STATUS_READY, SCENARIO_SET_STATUS_FAILED, SCENARIO_SET_STATUS_CANCELLED optional Statuses available for filtering this list request. `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `scenario_sets` array of object optional The scenario sets for the current page. **Show child properties** `bucket_name` string optional Example: `example name` Object storage bucket holding the scenario file. Unset while status is generating. `bucket_region` string optional Example: `example string` Object storage bucket region. Unset while status is generating. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the scenario set has been deleted. `description` string optional Example: `example string` Customer-supplied description. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `generator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model that produced the scenarios. Only set for goal-generated scenario sets. `library_scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the source library entry. Only set for library scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_LIBRARY`). `name` string optional Example: `example name` Customer-supplied name. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the set. Unset while status is generating. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set. `source_export_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Signals export UUID that produced this set. Only set for signal-generated scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED`). `source_goal_description` string optional Example: `example string` The goal that drove generation. Only set for goal_generated scenario sets. `source_kind` string, one of: SCENARIO_SET_SOURCE_KIND_UNSPECIFIED, SCENARIO_SET_SOURCE_KIND_USER_UPLOAD, SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED, SCENARIO_SET_SOURCE_KIND_LIBRARY, SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED optional Example: `SCENARIO_SET_SOURCE_KIND_UNSPECIFIED` How a scenario set was created. - SCENARIO_SET_SOURCE_KIND_USER_UPLOAD: Created from uploaded or inline scenarios. - SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED: Produced by goal-driven generation. - SCENARIO_SET_SOURCE_KIND_LIBRARY: Copied from a platform-curated library entry. - SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED: Produced from a completed Signals export. `spaces_key` string optional Example: `example string` Object storage key for the scenario file. Unset while status is generating. `status` string, one of: SCENARIO_SET_STATUS_UNSPECIFIED, SCENARIO_SET_STATUS_GENERATING, SCENARIO_SET_STATUS_READY, SCENARIO_SET_STATUS_FAILED, SCENARIO_SET_STATUS_CANCELLED optional Example: `SCENARIO_SET_STATUS_UNSPECIFIED` Lifecycle status of a scenario set. Uploaded sets are created as ready. Generated sets start as generating and then become ready, failed, or cancelled. - SCENARIO_SET_STATUS_GENERATING: Generation is in progress. The scenarios are not ready yet. - SCENARIO_SET_STATUS_READY: The scenario set is ready to use. - SCENARIO_SET_STATUS_FAILED: Generation failed. The scenario set has no readable scenarios. - SCENARIO_SET_STATUS_CANCELLED: Generation was cancelled before completion. `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the generation workflow. Only set for goal-generated scenario sets. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "available_sort_by": [ "SCENARIO_SET_SORT_FIELD_UNSPECIFIED" ], "available_sort_directions": [ "SORT_DIRECTION_UNSPECIFIED" ], "available_source_kinds": [ "SCENARIO_SET_SOURCE_KIND_UNSPECIFIED" ], "available_statuses": [ "SCENARIO_SET_STATUS_UNSPECIFIED" ], "links": { "pages": { "first": "example string", "last": "example string", "next": "example string", "previous": "example string" } }, "meta": { "page": 123, "pages": 123, "total": 123 }, "scenario_sets": [ { "bucket_name": "example name", "bucket_region": "example string", "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "description": "example string", "failure_reason": "example string", "generator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "library_scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "source_export_id": "123e4567-e89b-12d3-a456-426614174000", "source_goal_description": "example string", "source_kind": "SCENARIO_SET_SOURCE_KIND_UNSPECIFIED", "spaces_key": "example string", "status": "SCENARIO_SET_STATUS_UNSPECIFIED", "updated_at": "2023-01-01T00:00:00Z", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Scenario Set `/v2/gen-ai/scenario_sets` To create a scenario set, send a POST request to `/v2/gen-ai/scenario_sets`. Provide exactly one of `scenarios` or `file_upload_scenario_set`. The set is created in the ready state. #### Request Body: `application/json` `file_upload_scenario_set` object optional Uploaded scenario file to ingest. Provide this or `scenarios`, not both. `name` string optional Example: `support-agent-scenarios` The name of the scenario set. `scenarios` array of object optional Inline scenarios. Provide this or `file_upload_scenario_set`, not both. **Show child properties** `description` string optional Example: `example string` What the user tries to accomplish. Required. `exploration_budget` integer (int64) optional Example: `123` Number of journeys to explore for this scenario. Defaults to 1 if unset. `max_turns` integer (int64) optional Example: `123` Turn budget for the scenario. Falls back to the run-level default if unset. `name` string optional Example: `example name` Human-readable name for the scenario. Optional. `scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id for the scenario. Always generated by the API; any customer-supplied value is ignored and overwritten. `stopping_criteria` array of string optional Example: `["example string"]` Judge stopping criteria. Required; must contain at least one entry. `user_persona` string optional Example: `example string` How the user communicates (tone, role). Optional. ##### Request: `/v2/gen-ai/scenario_sets` ### Payload Content type `application/json` ```json { "file_upload_scenario_set": { "original_file_name": "example name", "size_in_bytes": "12345", "stored_object_key": "example string" }, "name": "support-agent-scenarios", "scenarios": [ { "description": "example string", "exploration_budget": 123, "max_turns": 123, "name": "example name", "scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "stopping_criteria": [ "example string" ], "user_persona": "example string" } ] } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_sets" \ -d '{ "name": "support-agent-scenarios", "scenarios": [ { "name": "Refund request", "description": "The user wants a refund for a delayed order", "user_persona": "Frustrated customer", "stopping_criteria": ["Refund is approved or a next step is clearly offered"], "max_turns": 8 } ] }' ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `scenario_set` object optional A team-owned collection of scenarios. **Show child properties** `bucket_name` string optional Example: `example name` Object storage bucket holding the scenario file. Unset while status is generating. `bucket_region` string optional Example: `example string` Object storage bucket region. Unset while status is generating. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the scenario set has been deleted. `description` string optional Example: `example string` Customer-supplied description. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `generator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model that produced the scenarios. Only set for goal-generated scenario sets. `library_scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the source library entry. Only set for library scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_LIBRARY`). `name` string optional Example: `example name` Customer-supplied name. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the set. Unset while status is generating. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set. `source_export_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Signals export UUID that produced this set. Only set for signal-generated scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED`). `source_goal_description` string optional Example: `example string` The goal that drove generation. Only set for goal_generated scenario sets. `source_kind` string, one of: SCENARIO_SET_SOURCE_KIND_UNSPECIFIED, SCENARIO_SET_SOURCE_KIND_USER_UPLOAD, SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED, SCENARIO_SET_SOURCE_KIND_LIBRARY, SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED optional Example: `SCENARIO_SET_SOURCE_KIND_UNSPECIFIED` How a scenario set was created. - SCENARIO_SET_SOURCE_KIND_USER_UPLOAD: Created from uploaded or inline scenarios. - SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED: Produced by goal-driven generation. - SCENARIO_SET_SOURCE_KIND_LIBRARY: Copied from a platform-curated library entry. - SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED: Produced from a completed Signals export. `spaces_key` string optional Example: `example string` Object storage key for the scenario file. Unset while status is generating. `status` string, one of: SCENARIO_SET_STATUS_UNSPECIFIED, SCENARIO_SET_STATUS_GENERATING, SCENARIO_SET_STATUS_READY, SCENARIO_SET_STATUS_FAILED, SCENARIO_SET_STATUS_CANCELLED optional Example: `SCENARIO_SET_STATUS_UNSPECIFIED` Lifecycle status of a scenario set. Uploaded sets are created as ready. Generated sets start as generating and then become ready, failed, or cancelled. - SCENARIO_SET_STATUS_GENERATING: Generation is in progress. The scenarios are not ready yet. - SCENARIO_SET_STATUS_READY: The scenario set is ready to use. - SCENARIO_SET_STATUS_FAILED: Generation failed. The scenario set has no readable scenarios. - SCENARIO_SET_STATUS_CANCELLED: Generation was cancelled before completion. `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the generation workflow. Only set for goal-generated scenario sets. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "scenario_set": { "bucket_name": "example name", "bucket_region": "example string", "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "description": "example string", "failure_reason": "example string", "generator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "library_scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "source_export_id": "123e4567-e89b-12d3-a456-426614174000", "source_goal_description": "example string", "source_kind": "SCENARIO_SET_SOURCE_KIND_UNSPECIFIED", "spaces_key": "example string", "status": "SCENARIO_SET_STATUS_UNSPECIFIED", "updated_at": "2023-01-01T00:00:00Z", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Presigned URLs for Scenario Set File Upload `/v2/gen-ai/scenario_sets/file_upload_presigned_urls` To create presigned URLs for uploading a scenario set file, send a POST request to `/v2/gen-ai/scenario_sets/file_upload_presigned_urls`. After uploading, pass the stored object in Create Scenario Set as `file_upload_scenario_set`. #### 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/scenario_sets/file_upload_presigned_urls` ### Payload Content type `application/json` ```json { "files": [ { "file_name": "example name", "file_size": "12345" } ] } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_sets/file_upload_presigned_urls" \ -d '{ "files": [{ "file_name": "scenarios.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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `request_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` The ID generated for the request for Presigned URLs. `uploads` array of object optional A list of generated presigned URLs and object keys, one per file. **Show child properties** `expires_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` The time the url expires at. `object_key` string optional Example: `example string` The unique object key to store the file as. `original_file_name` string optional Example: `example name` The original file name. `presigned_url` string optional Example: `example string` The actual presigned URL the client can use to upload the file directly. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Generate Scenario Set `/v2/gen-ai/scenario_sets/generate` To dispatch goal-driven scenario generation, send a POST request to `/v2/gen-ai/scenario_sets/generate`. The scenario set is returned in the generating state. Poll the retrieve scenario set endpoint until the set reaches a ready, failed, or cancelled status. #### Request Body: `application/json` `generator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional model to use for generation. Platform default when unset. `goal_description` string optional Example: `Test how the agent handles refund requests` The goal that drives scenario generation. `name` string optional Example: `billing-support-generated` The name of the scenario set to create. `num_scenarios` integer (int64) optional Example: `123` Number of scenarios to generate. Defaults to 1 if unset. ##### Request: `/v2/gen-ai/scenario_sets/generate` ### Payload Content type `application/json` ```json { "generator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "goal_description": "Test how the agent handles refund requests", "name": "billing-support-generated", "num_scenarios": 123 } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_sets/generate" \ -d '{ "name": "billing-support-generated", "goal_description": "Test how the agent handles refund requests", "num_scenarios": 4 }' ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `scenario_set` object optional A team-owned collection of scenarios. **Show child properties** `bucket_name` string optional Example: `example name` Object storage bucket holding the scenario file. Unset while status is generating. `bucket_region` string optional Example: `example string` Object storage bucket region. Unset while status is generating. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the scenario set has been deleted. `description` string optional Example: `example string` Customer-supplied description. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `generator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model that produced the scenarios. Only set for goal-generated scenario sets. `library_scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the source library entry. Only set for library scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_LIBRARY`). `name` string optional Example: `example name` Customer-supplied name. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the set. Unset while status is generating. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set. `source_export_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Signals export UUID that produced this set. Only set for signal-generated scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED`). `source_goal_description` string optional Example: `example string` The goal that drove generation. Only set for goal_generated scenario sets. `source_kind` string, one of: SCENARIO_SET_SOURCE_KIND_UNSPECIFIED, SCENARIO_SET_SOURCE_KIND_USER_UPLOAD, SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED, SCENARIO_SET_SOURCE_KIND_LIBRARY, SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED optional Example: `SCENARIO_SET_SOURCE_KIND_UNSPECIFIED` How a scenario set was created. - SCENARIO_SET_SOURCE_KIND_USER_UPLOAD: Created from uploaded or inline scenarios. - SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED: Produced by goal-driven generation. - SCENARIO_SET_SOURCE_KIND_LIBRARY: Copied from a platform-curated library entry. - SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED: Produced from a completed Signals export. `spaces_key` string optional Example: `example string` Object storage key for the scenario file. Unset while status is generating. `status` string, one of: SCENARIO_SET_STATUS_UNSPECIFIED, SCENARIO_SET_STATUS_GENERATING, SCENARIO_SET_STATUS_READY, SCENARIO_SET_STATUS_FAILED, SCENARIO_SET_STATUS_CANCELLED optional Example: `SCENARIO_SET_STATUS_UNSPECIFIED` Lifecycle status of a scenario set. Uploaded sets are created as ready. Generated sets start as generating and then become ready, failed, or cancelled. - SCENARIO_SET_STATUS_GENERATING: Generation is in progress. The scenarios are not ready yet. - SCENARIO_SET_STATUS_READY: The scenario set is ready to use. - SCENARIO_SET_STATUS_FAILED: Generation failed. The scenario set has no readable scenarios. - SCENARIO_SET_STATUS_CANCELLED: Generation was cancelled before completion. `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the generation workflow. Only set for goal-generated scenario sets. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "scenario_set": { "bucket_name": "example name", "bucket_region": "example string", "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "description": "example string", "failure_reason": "example string", "generator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "library_scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "source_export_id": "123e4567-e89b-12d3-a456-426614174000", "source_goal_description": "example string", "source_kind": "SCENARIO_SET_SOURCE_KIND_UNSPECIFIED", "spaces_key": "example string", "status": "SCENARIO_SET_STATUS_UNSPECIFIED", "updated_at": "2023-01-01T00:00:00Z", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Scenario Set `/v2/gen-ai/scenario_sets/{scenario_set_uuid}` To retrieve a scenario set, send a GET request to `/v2/gen-ai/scenario_sets/{scenario_set_uuid}`. #### Path Parameters `scenario_set_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the scenario set. ##### Request: `/v2/gen-ai/scenario_sets/{scenario_set_uuid}` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_sets/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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `scenario_set` object optional A team-owned collection of scenarios. **Show child properties** `bucket_name` string optional Example: `example name` Object storage bucket holding the scenario file. Unset while status is generating. `bucket_region` string optional Example: `example string` Object storage bucket region. Unset while status is generating. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the scenario set has been deleted. `description` string optional Example: `example string` Customer-supplied description. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `generator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model that produced the scenarios. Only set for goal-generated scenario sets. `library_scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the source library entry. Only set for library scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_LIBRARY`). `name` string optional Example: `example name` Customer-supplied name. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the set. Unset while status is generating. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set. `source_export_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Signals export UUID that produced this set. Only set for signal-generated scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED`). `source_goal_description` string optional Example: `example string` The goal that drove generation. Only set for goal_generated scenario sets. `source_kind` string, one of: SCENARIO_SET_SOURCE_KIND_UNSPECIFIED, SCENARIO_SET_SOURCE_KIND_USER_UPLOAD, SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED, SCENARIO_SET_SOURCE_KIND_LIBRARY, SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED optional Example: `SCENARIO_SET_SOURCE_KIND_UNSPECIFIED` How a scenario set was created. - SCENARIO_SET_SOURCE_KIND_USER_UPLOAD: Created from uploaded or inline scenarios. - SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED: Produced by goal-driven generation. - SCENARIO_SET_SOURCE_KIND_LIBRARY: Copied from a platform-curated library entry. - SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED: Produced from a completed Signals export. `spaces_key` string optional Example: `example string` Object storage key for the scenario file. Unset while status is generating. `status` string, one of: SCENARIO_SET_STATUS_UNSPECIFIED, SCENARIO_SET_STATUS_GENERATING, SCENARIO_SET_STATUS_READY, SCENARIO_SET_STATUS_FAILED, SCENARIO_SET_STATUS_CANCELLED optional Example: `SCENARIO_SET_STATUS_UNSPECIFIED` Lifecycle status of a scenario set. Uploaded sets are created as ready. Generated sets start as generating and then become ready, failed, or cancelled. - SCENARIO_SET_STATUS_GENERATING: Generation is in progress. The scenarios are not ready yet. - SCENARIO_SET_STATUS_READY: The scenario set is ready to use. - SCENARIO_SET_STATUS_FAILED: Generation failed. The scenario set has no readable scenarios. - SCENARIO_SET_STATUS_CANCELLED: Generation was cancelled before completion. `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the generation workflow. Only set for goal-generated scenario sets. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "scenario_set": { "bucket_name": "example name", "bucket_region": "example string", "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "description": "example string", "failure_reason": "example string", "generator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "library_scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "source_export_id": "123e4567-e89b-12d3-a456-426614174000", "source_goal_description": "example string", "source_kind": "SCENARIO_SET_SOURCE_KIND_UNSPECIFIED", "spaces_key": "example string", "status": "SCENARIO_SET_STATUS_UNSPECIFIED", "updated_at": "2023-01-01T00:00:00Z", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Scenario Set `/v2/gen-ai/scenario_sets/{scenario_set_uuid}` To update a scenario set in place, send a PUT request to `/v2/gen-ai/scenario_sets/{scenario_set_uuid}`. Provide a new `name` and/or replacement `scenarios`. At least one is required. Replacing contents keeps the same scenario set UUID, remints scenario UUIDs, and is rejected unless the set is ready and no simulation run references it. There is no file-upload path on update. #### Path Parameters `scenario_set_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the scenario set to update. Returned by `CreateScenarioSet` and listed via `ListScenarioSets`. #### Request Body: `application/json` `name` string optional Example: `example name` Optional new name. When set, must be non-empty and at most 255 characters. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set to update. `scenarios` array of object optional Optional inline scenarios to replace the set contents. At least one of name or scenarios is required. **Show child properties** `description` string optional Example: `example string` What the user tries to accomplish. Required. `exploration_budget` integer (int64) optional Example: `123` Number of journeys to explore for this scenario. Defaults to 1 if unset. `max_turns` integer (int64) optional Example: `123` Turn budget for the scenario. Falls back to the run-level default if unset. `name` string optional Example: `example name` Human-readable name for the scenario. Optional. `scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id for the scenario. Always generated by the API; any customer-supplied value is ignored and overwritten. `stopping_criteria` array of string optional Example: `["example string"]` Judge stopping criteria. Required; must contain at least one entry. `user_persona` string optional Example: `example string` How the user communicates (tone, role). Optional. ##### Request: `/v2/gen-ai/scenario_sets/{scenario_set_uuid}` ### Payload Content type `application/json` ```json { "name": "example name", "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "scenarios": [ { "description": "example string", "exploration_budget": 123, "max_turns": 123, "name": "example name", "scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "stopping_criteria": [ "example string" ], "user_persona": "example string" } ] } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_sets/12345678-1234-1234-1234-123456789012" \ -d '{ "name": "My new scenario set name" }' ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `scenario_set` object optional A team-owned collection of scenarios. **Show child properties** `bucket_name` string optional Example: `example name` Object storage bucket holding the scenario file. Unset while status is generating. `bucket_region` string optional Example: `example string` Object storage bucket region. Unset while status is generating. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the scenario set has been deleted. `description` string optional Example: `example string` Customer-supplied description. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `generator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model that produced the scenarios. Only set for goal-generated scenario sets. `library_scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the source library entry. Only set for library scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_LIBRARY`). `name` string optional Example: `example name` Customer-supplied name. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the set. Unset while status is generating. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set. `source_export_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Signals export UUID that produced this set. Only set for signal-generated scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED`). `source_goal_description` string optional Example: `example string` The goal that drove generation. Only set for goal_generated scenario sets. `source_kind` string, one of: SCENARIO_SET_SOURCE_KIND_UNSPECIFIED, SCENARIO_SET_SOURCE_KIND_USER_UPLOAD, SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED, SCENARIO_SET_SOURCE_KIND_LIBRARY, SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED optional Example: `SCENARIO_SET_SOURCE_KIND_UNSPECIFIED` How a scenario set was created. - SCENARIO_SET_SOURCE_KIND_USER_UPLOAD: Created from uploaded or inline scenarios. - SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED: Produced by goal-driven generation. - SCENARIO_SET_SOURCE_KIND_LIBRARY: Copied from a platform-curated library entry. - SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED: Produced from a completed Signals export. `spaces_key` string optional Example: `example string` Object storage key for the scenario file. Unset while status is generating. `status` string, one of: SCENARIO_SET_STATUS_UNSPECIFIED, SCENARIO_SET_STATUS_GENERATING, SCENARIO_SET_STATUS_READY, SCENARIO_SET_STATUS_FAILED, SCENARIO_SET_STATUS_CANCELLED optional Example: `SCENARIO_SET_STATUS_UNSPECIFIED` Lifecycle status of a scenario set. Uploaded sets are created as ready. Generated sets start as generating and then become ready, failed, or cancelled. - SCENARIO_SET_STATUS_GENERATING: Generation is in progress. The scenarios are not ready yet. - SCENARIO_SET_STATUS_READY: The scenario set is ready to use. - SCENARIO_SET_STATUS_FAILED: Generation failed. The scenario set has no readable scenarios. - SCENARIO_SET_STATUS_CANCELLED: Generation was cancelled before completion. `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the generation workflow. Only set for goal-generated scenario sets. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "scenario_set": { "bucket_name": "example name", "bucket_region": "example string", "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "description": "example string", "failure_reason": "example string", "generator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "library_scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "source_export_id": "123e4567-e89b-12d3-a456-426614174000", "source_goal_description": "example string", "source_kind": "SCENARIO_SET_SOURCE_KIND_UNSPECIFIED", "spaces_key": "example string", "status": "SCENARIO_SET_STATUS_UNSPECIFIED", "updated_at": "2023-01-01T00:00:00Z", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Scenario Set `/v2/gen-ai/scenario_sets/{scenario_set_uuid}` To delete a scenario set, send a DELETE request to `/v2/gen-ai/scenario_sets/{scenario_set_uuid}`. A scenario set that is referenced by a simulation run cannot be deleted. #### Path Parameters `scenario_set_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the scenario set to delete. Returned by `CreateScenarioSet` and listed via `ListScenarioSets`. A set still referenced by a simulation run cannot be deleted. ##### Request: `/v2/gen-ai/scenario_sets/{scenario_set_uuid}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_sets/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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the deleted scenario set. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Scenario Set Download URL `/v2/gen-ai/scenario_sets/{scenario_set_uuid}/download_url` To retrieve a presigned download URL for a scenario set file, send a GET request to `/v2/gen-ai/scenario_sets/{scenario_set_uuid}/download_url`. #### Path Parameters `scenario_set_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the scenario set. ##### Request: `/v2/gen-ai/scenario_sets/{scenario_set_uuid}/download_url` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_sets/12345678-1234-1234-1234-123456789012/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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 scenario set 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "download_url": "example string", "expires_at": "2023-01-01T00:00:00Z" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Duplicate Scenario Set `/v2/gen-ai/scenario_sets/{scenario_set_uuid}/duplicate` To duplicate a scenario set, send a POST request to `/v2/gen-ai/scenario_sets/{scenario_set_uuid}/duplicate`. The source set must be ready. The new set is named `{original name} duplicate` and contains a copy of the source scenarios. #### Path Parameters `scenario_set_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the scenario set to duplicate. #### Request Body: `application/json` `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set to duplicate. ##### Request: `/v2/gen-ai/scenario_sets/{scenario_set_uuid}/duplicate` ### Payload Content type `application/json` ```json { "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_sets/12345678-1234-1234-1234-123456789012/duplicate" \ -d '{ "scenario_set_uuid": "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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `scenario_set` object optional A team-owned collection of scenarios. **Show child properties** `bucket_name` string optional Example: `example name` Object storage bucket holding the scenario file. Unset while status is generating. `bucket_region` string optional Example: `example string` Object storage bucket region. Unset while status is generating. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the scenario set has been deleted. `description` string optional Example: `example string` Customer-supplied description. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `generator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model that produced the scenarios. Only set for goal-generated scenario sets. `library_scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the source library entry. Only set for library scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_LIBRARY`). `name` string optional Example: `example name` Customer-supplied name. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the set. Unset while status is generating. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set. `source_export_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Signals export UUID that produced this set. Only set for signal-generated scenario sets (`source_kind=SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED`). `source_goal_description` string optional Example: `example string` The goal that drove generation. Only set for goal_generated scenario sets. `source_kind` string, one of: SCENARIO_SET_SOURCE_KIND_UNSPECIFIED, SCENARIO_SET_SOURCE_KIND_USER_UPLOAD, SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED, SCENARIO_SET_SOURCE_KIND_LIBRARY, SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED optional Example: `SCENARIO_SET_SOURCE_KIND_UNSPECIFIED` How a scenario set was created. - SCENARIO_SET_SOURCE_KIND_USER_UPLOAD: Created from uploaded or inline scenarios. - SCENARIO_SET_SOURCE_KIND_GOAL_GENERATED: Produced by goal-driven generation. - SCENARIO_SET_SOURCE_KIND_LIBRARY: Copied from a platform-curated library entry. - SCENARIO_SET_SOURCE_KIND_SIGNAL_GENERATED: Produced from a completed Signals export. `spaces_key` string optional Example: `example string` Object storage key for the scenario file. Unset while status is generating. `status` string, one of: SCENARIO_SET_STATUS_UNSPECIFIED, SCENARIO_SET_STATUS_GENERATING, SCENARIO_SET_STATUS_READY, SCENARIO_SET_STATUS_FAILED, SCENARIO_SET_STATUS_CANCELLED optional Example: `SCENARIO_SET_STATUS_UNSPECIFIED` Lifecycle status of a scenario set. Uploaded sets are created as ready. Generated sets start as generating and then become ready, failed, or cancelled. - SCENARIO_SET_STATUS_GENERATING: Generation is in progress. The scenarios are not ready yet. - SCENARIO_SET_STATUS_READY: The scenario set is ready to use. - SCENARIO_SET_STATUS_FAILED: Generation failed. The scenario set has no readable scenarios. - SCENARIO_SET_STATUS_CANCELLED: Generation was cancelled before completion. `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the generation workflow. Only set for goal-generated scenario sets. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "scenario_set": { "bucket_name": "example name", "bucket_region": "example string", "created_at": "2023-01-01T00:00:00Z", "deleted_at": "2023-01-01T00:00:00Z", "description": "example string", "failure_reason": "example string", "generator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "library_scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "source_export_id": "123e4567-e89b-12d3-a456-426614174000", "source_goal_description": "example string", "source_kind": "SCENARIO_SET_SOURCE_KIND_UNSPECIFIED", "spaces_key": "example string", "status": "SCENARIO_SET_STATUS_UNSPECIFIED", "updated_at": "2023-01-01T00:00:00Z", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Scenarios `/v2/gen-ai/scenario_sets/{scenario_set_uuid}/scenarios` To list the scenarios in a scenario set, send a GET request to `/v2/gen-ai/scenario_sets/{scenario_set_uuid}/scenarios`. #### Path Parameters `scenario_set_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the scenario set to read. #### Query Parameters `page` integer optional Example: `1` Page number. `per_page` integer optional Example: `1` Items per page. `search` string optional Example: `example string` Free-text search across name, description, and user_persona (case-insensitive substring match). Empty means no search. `sort_by` string, one of: SCENARIO_SORT_FIELD_UNSPECIFIED, SCENARIO_SORT_FIELD_FILE_ORDER, SCENARIO_SORT_FIELD_NAME, SCENARIO_SORT_FIELD_DESCRIPTION optional Example: `SCENARIO_SORT_FIELD_UNSPECIFIED` Field to sort by. Defaults to original file order when unspecified. - SCENARIO_SORT_FIELD_FILE_ORDER: Preserve original file order. Default. - SCENARIO_SORT_FIELD_NAME: Sort by scenario name (case-insensitive). Empty names sort last. - SCENARIO_SORT_FIELD_DESCRIPTION: Sort by scenario description (case-insensitive). Default: `SCENARIO_SORT_FIELD_UNSPECIFIED` `sort_direction` string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Example: `SORT_DIRECTION_UNSPECIFIED` Sort direction. Defaults to ascending when unspecified. Default: `SORT_DIRECTION_UNSPECIFIED` ##### Request: `/v2/gen-ai/scenario_sets/{scenario_set_uuid}/scenarios` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/scenario_sets/12345678-1234-1234-1234-123456789012/scenarios" ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `available_sort_by` array of string, one of: SCENARIO_SORT_FIELD_UNSPECIFIED, SCENARIO_SORT_FIELD_FILE_ORDER, SCENARIO_SORT_FIELD_NAME, SCENARIO_SORT_FIELD_DESCRIPTION optional Sort-by values available for this list request. `available_sort_directions` array of string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Sort-direction values available for this list request. `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `scenarios` array of object optional The scenarios for the current page. **Show child properties** `description` string optional Example: `example string` What the user tries to accomplish. Required. `exploration_budget` integer (int64) optional Example: `123` Number of journeys to explore for this scenario. Defaults to 1 if unset. `max_turns` integer (int64) optional Example: `123` Turn budget for the scenario. Falls back to the run-level default if unset. `name` string optional Example: `example name` Human-readable name for the scenario. Optional. `scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id for the scenario. Always generated by the API; any customer-supplied value is ignored and overwritten. `stopping_criteria` array of string optional Example: `["example string"]` Judge stopping criteria. Required; must contain at least one entry. `user_persona` string optional Example: `example string` How the user communicates (tone, role). Optional. **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "available_sort_by": [ "SCENARIO_SORT_FIELD_UNSPECIFIED" ], "available_sort_directions": [ "SORT_DIRECTION_UNSPECIFIED" ], "links": { "pages": { "first": "example string", "last": "example string", "next": "example string", "previous": "example string" } }, "meta": { "page": 123, "pages": 123, "total": 123 }, "scenarios": [ { "description": "example string", "exploration_budget": 123, "max_turns": 123, "name": "example name", "scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "stopping_criteria": [ "example string" ], "user_persona": "example string" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create scheduled indexing for knowledge base `/v2/gen-ai/scheduled-indexing` 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` ```json { "days": [ 123 ], "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000", "time": "example string" } ``` ### cURL ```bash curl --location --request POST 'https://api.digitalocean.com/v2/gen-ai/scheduled-indexing' \ --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN"' \ --header 'Content-Type: application/json' \ --data '{ "knowledge_base_uuid": "knowledge_base_uuid", "time": "18:00", "days": [ 1, 2, 3 ] }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `indexing_info` object optional Metadata for scheduled indexing entries **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Created at timestamp `days` array of integer (int32) optional Days for execution (day is represented same as in a cron expression, e.g. Monday begins with 1 ) `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted at timestamp (if soft deleted) `is_active` boolean optional Example: `true` Whether the schedule is currently active `knowledge_base_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Knowledge base uuid associated with this schedule `last_ran_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Last time the schedule was executed `next_run_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Next scheduled run `time` string optional Example: `example string` Scheduled time of execution (HH:MM:SS format) `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Updated at timestamp `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique identifier for the scheduled indexing entry **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Get Scheduled Indexing for Knowledge Base `/v2/gen-ai/scheduled-indexing/knowledge-base/{knowledge_base_uuid}` 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 ```bash curl --location --request GET 'https://api.digitalocean.com/v2/gen-ai/scheduled-indexing/knowledge-base/{knowledge_base_uuid}' \ --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' \ --header 'Content-Type: application/json' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `indexing_info` object optional Metadata for scheduled indexing entries **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Created at timestamp `days` array of integer (int32) optional Days for execution (day is represented same as in a cron expression, e.g. Monday begins with 1 ) `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted at timestamp (if soft deleted) `is_active` boolean optional Example: `true` Whether the schedule is currently active `knowledge_base_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Knowledge base uuid associated with this schedule `last_ran_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Last time the schedule was executed `next_run_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Next scheduled run `time` string optional Example: `example string` Scheduled time of execution (HH:MM:SS format) `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Updated at timestamp `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique identifier for the scheduled indexing entry **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Scheduled Indexing `/v2/gen-ai/scheduled-indexing/{uuid}` 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 ```bash curl --location --request DELETE 'https://api.digitalocean.com/v2/gen-ai/scheduled-indexing/{scheduled_indexing_id}' \ --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `indexing_info` object optional Metadata for scheduled indexing entries **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Created at timestamp `days` array of integer (int32) optional Days for execution (day is represented same as in a cron expression, e.g. Monday begins with 1 ) `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Deleted at timestamp (if soft deleted) `is_active` boolean optional Example: `true` Whether the schedule is currently active `knowledge_base_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Knowledge base uuid associated with this schedule `last_ran_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Last time the schedule was executed `next_run_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Next scheduled run `time` string optional Example: `example string` Scheduled time of execution (HH:MM:SS format) `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Updated at timestamp `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique identifier for the scheduled indexing entry **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Simulation Runs `/v2/gen-ai/simulation_runs` To list simulation runs, send a GET request to `/v2/gen-ai/simulation_runs`. #### Query Parameters `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional filter by scenario set. `page` integer optional Example: `1` Page number. `per_page` integer optional Example: `1` Items per page. `statuses` array of string (enum) optional Example: `["SIMULATION_RUN_STATUS_RUNNING"]` Filter by one or more statuses. Empty means no status filter. - SIMULATION_RUN_STATUS_PENDING: Accepted and queued, not yet executing. - SIMULATION_RUN_STATUS_RUNNING: Journeys are executing. - SIMULATION_RUN_STATUS_SUCCEEDED: All journeys finished successfully. - SIMULATION_RUN_STATUS_FAILED: The run failed, for example because of a timeout or workflow error. - SIMULATION_RUN_STATUS_CANCELLED: The run was cancelled. - SIMULATION_RUN_STATUS_EVALUATING: Journeys finished and an attached evaluation is running. Only reachable when the create request included evaluation_config. When the evaluation reaches a terminal status, its outcome is reflected in the simulation run status. - SIMULATION_RUN_STATUS_PARTIALLY_SUCCESSFUL: The simulation or its attached evaluation completed with a mixture of successful and failed results. `search` string optional Example: `example string` Free-text search across the run name and scenario set name (case-insensitive substring match). Empty means no search. `sort_by` string, one of: SIMULATION_RUN_SORT_FIELD_UNSPECIFIED, SIMULATION_RUN_SORT_FIELD_CREATED_AT, SIMULATION_RUN_SORT_FIELD_NAME, SIMULATION_RUN_SORT_FIELD_STATUS, SIMULATION_RUN_SORT_FIELD_UPDATED_AT optional Example: `SIMULATION_RUN_SORT_FIELD_UNSPECIFIED` Field to sort by. Defaults to creation date when unspecified. - SIMULATION_RUN_SORT_FIELD_CREATED_AT: Sort by creation date. Default. - SIMULATION_RUN_SORT_FIELD_NAME: Sort by customer-supplied run name (case-insensitive). - SIMULATION_RUN_SORT_FIELD_STATUS: Sort by status using lifecycle order (pending → running → terminal). - SIMULATION_RUN_SORT_FIELD_UPDATED_AT: Sort by last update date. Default: `SIMULATION_RUN_SORT_FIELD_UNSPECIFIED` `sort_direction` string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Example: `SORT_DIRECTION_UNSPECIFIED` Sort direction. Defaults to descending when unspecified. Default: `SORT_DIRECTION_UNSPECIFIED` ##### Request: `/v2/gen-ai/simulation_runs` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/simulation_runs" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `available_sort_by` array of string, one of: SIMULATION_RUN_SORT_FIELD_UNSPECIFIED, SIMULATION_RUN_SORT_FIELD_CREATED_AT, SIMULATION_RUN_SORT_FIELD_NAME, SIMULATION_RUN_SORT_FIELD_STATUS, SIMULATION_RUN_SORT_FIELD_UPDATED_AT optional Sort-by values available for this list request. `available_sort_directions` array of string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Sort-direction values available for this list request. `available_statuses` array of string (enum) optional Statuses available for filtering this list request. `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages `simulation_runs` array of object optional The simulation runs for the current page. **Show child properties** `agent_config` object optional Configuration of the candidate agent under test for a simulation run. **Show child properties** `agent_deployment_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional agent deployment to run. Defaults to the agent's current deployment when unset. `agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the agent to exercise as the candidate. `name` string optional Example: `example name` Display name of the candidate agent. Persisted with the run. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `created_by_user_email` string optional Example: `example@example.com` Email of the user who triggered this run. `created_by_user_id` string (uint64) optional Example: `12345` User id of the actor who triggered this run. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the run has been deleted. `evaluation_run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the evaluation run reserved for this simulation, when the create request included evaluation_config. Empty when no evaluation is attached. `exploration_budget` integer (int64) optional Example: `123` Optional run-level journeys-per-scenario override. When set, overrides each scenario's exploration_budget. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `journeys_finished` integer (int64) optional Example: `123` Number of journeys that have finished (successfully or not). `judge_model_name` string optional Example: `example name` Display name of the judge model (from the model catalog). `judge_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model used by the judge. `max_turns` integer (int64) optional Example: `123` Optional run-level turn budget. When set, overrides each scenario's max_turns. `name` string optional Example: `example name` Optional run name. `result_summary` object optional Aggregated final result of a simulation run: verdict counts plus token and duration totals. **Show child properties** `token_usage` object optional Per-actor token accounting for a run or journey. **Show child properties** `candidate_agent_tokens` string (uint64) optional Example: `12345` Tokens consumed by the candidate agent. `generator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the scenario generator. `judge_tokens` string (uint64) optional Example: `12345` Tokens consumed by the judge. `simulator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the user simulator. `total_tokens` string (uint64) optional Example: `12345` Total tokens across all actors. `total_duration_sec` string (uint64) optional Example: `12345` Total wall-clock duration across the run, in seconds. `verdict_counts` object optional Breakdown of journey outcomes by judge verdict. Reused wherever a success / failure / inconclusive tally is reported (run row, result summary, per-scenario rollup). **Show child properties** `failure_count` integer (int64) optional Example: `123` Number of journeys with a FAILURE verdict. `inconclusive_count` integer (int64) optional Example: `123` Number of journeys with an INCONCLUSIVE verdict. `success_count` integer (int64) optional Example: `123` Number of journeys with a SUCCESS verdict. `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the run. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the scenario set for this run. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set being executed (must exist at run create). `status` string (enum) optional Example: `SIMULATION_RUN_STATUS_UNSPECIFIED` Lifecycle status of a simulation run. - SIMULATION_RUN_STATUS_PENDING: Accepted and queued, not yet executing. - SIMULATION_RUN_STATUS_RUNNING: Journeys are executing. - SIMULATION_RUN_STATUS_SUCCEEDED: All journeys finished successfully. - SIMULATION_RUN_STATUS_FAILED: The run failed, for example because of a timeout or workflow error. - SIMULATION_RUN_STATUS_CANCELLED: The run was cancelled. - SIMULATION_RUN_STATUS_EVALUATING: Journeys finished and an attached evaluation is running. Only reachable when the create request included evaluation_config. When the evaluation reaches a terminal status, its outcome is reflected in the simulation run status. - SIMULATION_RUN_STATUS_PARTIALLY_SUCCESSFUL: The simulation or its attached evaluation completed with a mixture of successful and failed results. `total_journeys` integer (int64) optional Example: `123` Total number of journeys (sum of exploration budgets). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `user_simulator_config` object optional Optional user simulator model settings such as temperature and max_tokens. `user_simulator_model_name` string optional Example: `example name` Display name of the user simulator model (from the model catalog). `user_simulator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model used by the user simulator. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the workflow executing this 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "available_sort_by": [ "SIMULATION_RUN_SORT_FIELD_UNSPECIFIED" ], "available_sort_directions": [ "SORT_DIRECTION_UNSPECIFIED" ], "available_statuses": [ "SIMULATION_RUN_STATUS_UNSPECIFIED" ], "links": { "pages": { "first": "example string", "last": "example string", "next": "example string", "previous": "example string" } }, "meta": { "page": 123, "pages": 123, "total": 123 }, "simulation_runs": [ { "created_at": "2023-01-01T00:00:00Z", "created_by_user_email": "example@example.com", "created_by_user_id": "12345", "deleted_at": "2023-01-01T00:00:00Z", "evaluation_run_uuid": "123e4567-e89b-12d3-a456-426614174000", "exploration_budget": 123, "failure_reason": "example string", "journeys_finished": 123, "judge_model_name": "example name", "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "max_turns": 123, "name": "example name", "run_uuid": "123e4567-e89b-12d3-a456-426614174000", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "status": "SIMULATION_RUN_STATUS_UNSPECIFIED", "total_journeys": 123, "updated_at": "2023-01-01T00:00:00Z", "user_simulator_model_name": "example name", "user_simulator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create Simulation Run `/v2/gen-ai/simulation_runs` To create a simulation run, send a POST request to `/v2/gen-ai/simulation_runs`. The scenario set must be ready. Judge and user simulator models are optional and use platform defaults when omitted. The run is returned in the pending state. #### Request Body: `application/json` `agent_config` object optional Configuration of the candidate agent under test for a simulation run. **Show child properties** `agent_deployment_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional agent deployment to run. Defaults to the agent's current deployment when unset. `agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the agent to exercise as the candidate. `name` string optional Example: `example name` Display name of the candidate agent. Persisted with the run. `evaluation_config` object optional Optional configuration that opts a simulation run into an evaluation. When included on the create-run request, the platform reserves a model_evaluation_run linked to this simulation run and dispatches the evaluation automatically after the simulation finishes. The evaluation reuses the simulation run's judge_model_uuid. **Show child properties** `metric_uuids` array of string optional Example: `["example string"]` Evaluation metric UUIDs (from the evaluation metrics catalog). Must be simulation-eligible (multi-turn) metrics; the create request is rejected if any UUID is unknown or ineligible. `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. `exploration_budget` integer (int64) optional Example: `123` Optional run-level journeys-per-scenario override. When set, overrides each scenario's exploration_budget. `judge_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional model override for the judge. Platform default when unset. `max_turns` integer (int64) optional Example: `123` Optional run-level turn budget. When set, overrides each scenario's max_turns. `name` string optional Example: `example name` Optional run name. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the existing scenario set to execute. The set must be ready. `user_simulator_config` object optional Optional user simulator model settings such as temperature and max_tokens. `user_simulator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional model override for the user simulator. Platform default when unset. ##### Request: `/v2/gen-ai/simulation_runs` ### Payload Content type `application/json` ```json { "agent_config": { "agent_deployment_uuid": "123e4567-e89b-12d3-a456-426614174000", "agent_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name" }, "evaluation_config": { "metric_uuids": [ "example string" ], "star_metric": { "metric_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name", "success_threshold": 123, "success_threshold_pct": 123 } }, "exploration_budget": 123, "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "max_turns": 123, "name": "example name", "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "user_simulator_model_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/simulation_runs" \ -d '{ "name": "my-simulation-run", "scenario_set_uuid": "12345678-1234-1234-1234-123456789012", "agent_config": { "agent_uuid": "223e4567-e89b-12d3-a456-426614174001", "name": "support-agent" }, "judge_model_uuid": "323e4567-e89b-12d3-a456-426614174002", "user_simulator_model_uuid": "423e4567-e89b-12d3-a456-426614174003", "evaluation_config": { "metric_uuids": [ "523e4567-e89b-12d3-a456-426614174004" ], "star_metric": { "metric_uuid": "523e4567-e89b-12d3-a456-426614174004", "success_threshold": 80 } } }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `simulation_run` object optional One execution of a scenario set against a candidate agent. **Show child properties** `agent_config` object optional Configuration of the candidate agent under test for a simulation run. **Show child properties** `agent_deployment_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional agent deployment to run. Defaults to the agent's current deployment when unset. `agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the agent to exercise as the candidate. `name` string optional Example: `example name` Display name of the candidate agent. Persisted with the run. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `created_by_user_email` string optional Example: `example@example.com` Email of the user who triggered this run. `created_by_user_id` string (uint64) optional Example: `12345` User id of the actor who triggered this run. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the run has been deleted. `evaluation_run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the evaluation run reserved for this simulation, when the create request included evaluation_config. Empty when no evaluation is attached. `exploration_budget` integer (int64) optional Example: `123` Optional run-level journeys-per-scenario override. When set, overrides each scenario's exploration_budget. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `journeys_finished` integer (int64) optional Example: `123` Number of journeys that have finished (successfully or not). `judge_model_name` string optional Example: `example name` Display name of the judge model (from the model catalog). `judge_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model used by the judge. `max_turns` integer (int64) optional Example: `123` Optional run-level turn budget. When set, overrides each scenario's max_turns. `name` string optional Example: `example name` Optional run name. `result_summary` object optional Aggregated final result of a simulation run: verdict counts plus token and duration totals. **Show child properties** `token_usage` object optional Per-actor token accounting for a run or journey. **Show child properties** `candidate_agent_tokens` string (uint64) optional Example: `12345` Tokens consumed by the candidate agent. `generator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the scenario generator. `judge_tokens` string (uint64) optional Example: `12345` Tokens consumed by the judge. `simulator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the user simulator. `total_tokens` string (uint64) optional Example: `12345` Total tokens across all actors. `total_duration_sec` string (uint64) optional Example: `12345` Total wall-clock duration across the run, in seconds. `verdict_counts` object optional Breakdown of journey outcomes by judge verdict. Reused wherever a success / failure / inconclusive tally is reported (run row, result summary, per-scenario rollup). **Show child properties** `failure_count` integer (int64) optional Example: `123` Number of journeys with a FAILURE verdict. `inconclusive_count` integer (int64) optional Example: `123` Number of journeys with an INCONCLUSIVE verdict. `success_count` integer (int64) optional Example: `123` Number of journeys with a SUCCESS verdict. `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the run. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the scenario set for this run. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set being executed (must exist at run create). `status` string (enum) optional Example: `SIMULATION_RUN_STATUS_UNSPECIFIED` Lifecycle status of a simulation run. - SIMULATION_RUN_STATUS_PENDING: Accepted and queued, not yet executing. - SIMULATION_RUN_STATUS_RUNNING: Journeys are executing. - SIMULATION_RUN_STATUS_SUCCEEDED: All journeys finished successfully. - SIMULATION_RUN_STATUS_FAILED: The run failed, for example because of a timeout or workflow error. - SIMULATION_RUN_STATUS_CANCELLED: The run was cancelled. - SIMULATION_RUN_STATUS_EVALUATING: Journeys finished and an attached evaluation is running. Only reachable when the create request included evaluation_config. When the evaluation reaches a terminal status, its outcome is reflected in the simulation run status. - SIMULATION_RUN_STATUS_PARTIALLY_SUCCESSFUL: The simulation or its attached evaluation completed with a mixture of successful and failed results. `total_journeys` integer (int64) optional Example: `123` Total number of journeys (sum of exploration budgets). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `user_simulator_config` object optional Optional user simulator model settings such as temperature and max_tokens. `user_simulator_model_name` string optional Example: `example name` Display name of the user simulator model (from the model catalog). `user_simulator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model used by the user simulator. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the workflow executing this 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "simulation_run": { "agent_config": { "agent_deployment_uuid": "123e4567-e89b-12d3-a456-426614174000", "agent_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name" }, "created_at": "2023-01-01T00:00:00Z", "created_by_user_email": "example@example.com", "created_by_user_id": "12345", "deleted_at": "2023-01-01T00:00:00Z", "evaluation_run_uuid": "123e4567-e89b-12d3-a456-426614174000", "exploration_budget": 123, "failure_reason": "example string", "journeys_finished": 123, "judge_model_name": "example name", "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "max_turns": 123, "name": "example name", "result_summary": { "total_duration_sec": "12345" }, "run_uuid": "123e4567-e89b-12d3-a456-426614174000", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "status": "SIMULATION_RUN_STATUS_UNSPECIFIED", "total_journeys": 123, "updated_at": "2023-01-01T00:00:00Z", "user_simulator_model_name": "example name", "user_simulator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Simulation Run `/v2/gen-ai/simulation_runs/{run_uuid}` To retrieve a simulation run, send a GET request to `/v2/gen-ai/simulation_runs/{run_uuid}`. #### Path Parameters `run_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the simulation run. ##### Request: `/v2/gen-ai/simulation_runs/{run_uuid}` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/simulation_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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `scenario_results` array of object optional Per-scenario breakdown of journey outcomes, aggregated from journey rows. **Show child properties** `journeys_finished` integer (int64) optional Example: `123` Journeys that have finished (successfully or not). `scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario. `total_journeys` integer (int64) optional Example: `123` Total journeys for this scenario (its exploration budget). `verdict_counts` object optional Breakdown of journey outcomes by judge verdict. Reused wherever a success / failure / inconclusive tally is reported (run row, result summary, per-scenario rollup). **Show child properties** `failure_count` integer (int64) optional Example: `123` Number of journeys with a FAILURE verdict. `inconclusive_count` integer (int64) optional Example: `123` Number of journeys with an INCONCLUSIVE verdict. `success_count` integer (int64) optional Example: `123` Number of journeys with a SUCCESS verdict. `simulation_run` object optional One execution of a scenario set against a candidate agent. **Show child properties** `agent_config` object optional Configuration of the candidate agent under test for a simulation run. **Show child properties** `agent_deployment_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional agent deployment to run. Defaults to the agent's current deployment when unset. `agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the agent to exercise as the candidate. `name` string optional Example: `example name` Display name of the candidate agent. Persisted with the run. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `created_by_user_email` string optional Example: `example@example.com` Email of the user who triggered this run. `created_by_user_id` string (uint64) optional Example: `12345` User id of the actor who triggered this run. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the run has been deleted. `evaluation_run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the evaluation run reserved for this simulation, when the create request included evaluation_config. Empty when no evaluation is attached. `exploration_budget` integer (int64) optional Example: `123` Optional run-level journeys-per-scenario override. When set, overrides each scenario's exploration_budget. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `journeys_finished` integer (int64) optional Example: `123` Number of journeys that have finished (successfully or not). `judge_model_name` string optional Example: `example name` Display name of the judge model (from the model catalog). `judge_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model used by the judge. `max_turns` integer (int64) optional Example: `123` Optional run-level turn budget. When set, overrides each scenario's max_turns. `name` string optional Example: `example name` Optional run name. `result_summary` object optional Aggregated final result of a simulation run: verdict counts plus token and duration totals. **Show child properties** `token_usage` object optional Per-actor token accounting for a run or journey. **Show child properties** `candidate_agent_tokens` string (uint64) optional Example: `12345` Tokens consumed by the candidate agent. `generator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the scenario generator. `judge_tokens` string (uint64) optional Example: `12345` Tokens consumed by the judge. `simulator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the user simulator. `total_tokens` string (uint64) optional Example: `12345` Total tokens across all actors. `total_duration_sec` string (uint64) optional Example: `12345` Total wall-clock duration across the run, in seconds. `verdict_counts` object optional Breakdown of journey outcomes by judge verdict. Reused wherever a success / failure / inconclusive tally is reported (run row, result summary, per-scenario rollup). **Show child properties** `failure_count` integer (int64) optional Example: `123` Number of journeys with a FAILURE verdict. `inconclusive_count` integer (int64) optional Example: `123` Number of journeys with an INCONCLUSIVE verdict. `success_count` integer (int64) optional Example: `123` Number of journeys with a SUCCESS verdict. `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the run. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the scenario set for this run. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set being executed (must exist at run create). `status` string (enum) optional Example: `SIMULATION_RUN_STATUS_UNSPECIFIED` Lifecycle status of a simulation run. - SIMULATION_RUN_STATUS_PENDING: Accepted and queued, not yet executing. - SIMULATION_RUN_STATUS_RUNNING: Journeys are executing. - SIMULATION_RUN_STATUS_SUCCEEDED: All journeys finished successfully. - SIMULATION_RUN_STATUS_FAILED: The run failed, for example because of a timeout or workflow error. - SIMULATION_RUN_STATUS_CANCELLED: The run was cancelled. - SIMULATION_RUN_STATUS_EVALUATING: Journeys finished and an attached evaluation is running. Only reachable when the create request included evaluation_config. When the evaluation reaches a terminal status, its outcome is reflected in the simulation run status. - SIMULATION_RUN_STATUS_PARTIALLY_SUCCESSFUL: The simulation or its attached evaluation completed with a mixture of successful and failed results. `total_journeys` integer (int64) optional Example: `123` Total number of journeys (sum of exploration budgets). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `user_simulator_config` object optional Optional user simulator model settings such as temperature and max_tokens. `user_simulator_model_name` string optional Example: `example name` Display name of the user simulator model (from the model catalog). `user_simulator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model used by the user simulator. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the workflow executing this 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "scenario_results": [ { "journeys_finished": 123, "scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "total_journeys": 123 } ], "simulation_run": { "agent_config": { "agent_deployment_uuid": "123e4567-e89b-12d3-a456-426614174000", "agent_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name" }, "created_at": "2023-01-01T00:00:00Z", "created_by_user_email": "example@example.com", "created_by_user_id": "12345", "deleted_at": "2023-01-01T00:00:00Z", "evaluation_run_uuid": "123e4567-e89b-12d3-a456-426614174000", "exploration_budget": 123, "failure_reason": "example string", "journeys_finished": 123, "judge_model_name": "example name", "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "max_turns": 123, "name": "example name", "result_summary": { "total_duration_sec": "12345" }, "run_uuid": "123e4567-e89b-12d3-a456-426614174000", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "status": "SIMULATION_RUN_STATUS_UNSPECIFIED", "total_journeys": 123, "updated_at": "2023-01-01T00:00:00Z", "user_simulator_model_name": "example name", "user_simulator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update Simulation Run `/v2/gen-ai/simulation_runs/{run_uuid}` To update a simulation run's display name, send a PUT request to `/v2/gen-ai/simulation_runs/{run_uuid}`. Only the name is mutable; run configuration and results are immutable. #### Path Parameters `run_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the simulation run to update. Returned by `CreateSimulationRun` and listed via `ListSimulationRuns`. #### Request Body: `application/json` `name` string optional Example: `example name` The new name of the run. `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the run to update. ##### Request: `/v2/gen-ai/simulation_runs/{run_uuid}` ### Payload Content type `application/json` ```json { "name": "example name", "run_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/simulation_runs/12345678-1234-1234-1234-123456789012" \ -d '{ "name": "My new simulation name" }' ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `simulation_run` object optional One execution of a scenario set against a candidate agent. **Show child properties** `agent_config` object optional Configuration of the candidate agent under test for a simulation run. **Show child properties** `agent_deployment_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional agent deployment to run. Defaults to the agent's current deployment when unset. `agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the agent to exercise as the candidate. `name` string optional Example: `example name` Display name of the candidate agent. Persisted with the run. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `created_by_user_email` string optional Example: `example@example.com` Email of the user who triggered this run. `created_by_user_id` string (uint64) optional Example: `12345` User id of the actor who triggered this run. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the run has been deleted. `evaluation_run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the evaluation run reserved for this simulation, when the create request included evaluation_config. Empty when no evaluation is attached. `exploration_budget` integer (int64) optional Example: `123` Optional run-level journeys-per-scenario override. When set, overrides each scenario's exploration_budget. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `journeys_finished` integer (int64) optional Example: `123` Number of journeys that have finished (successfully or not). `judge_model_name` string optional Example: `example name` Display name of the judge model (from the model catalog). `judge_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model used by the judge. `max_turns` integer (int64) optional Example: `123` Optional run-level turn budget. When set, overrides each scenario's max_turns. `name` string optional Example: `example name` Optional run name. `result_summary` object optional Aggregated final result of a simulation run: verdict counts plus token and duration totals. **Show child properties** `token_usage` object optional Per-actor token accounting for a run or journey. **Show child properties** `candidate_agent_tokens` string (uint64) optional Example: `12345` Tokens consumed by the candidate agent. `generator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the scenario generator. `judge_tokens` string (uint64) optional Example: `12345` Tokens consumed by the judge. `simulator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the user simulator. `total_tokens` string (uint64) optional Example: `12345` Total tokens across all actors. `total_duration_sec` string (uint64) optional Example: `12345` Total wall-clock duration across the run, in seconds. `verdict_counts` object optional Breakdown of journey outcomes by judge verdict. Reused wherever a success / failure / inconclusive tally is reported (run row, result summary, per-scenario rollup). **Show child properties** `failure_count` integer (int64) optional Example: `123` Number of journeys with a FAILURE verdict. `inconclusive_count` integer (int64) optional Example: `123` Number of journeys with an INCONCLUSIVE verdict. `success_count` integer (int64) optional Example: `123` Number of journeys with a SUCCESS verdict. `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the run. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the scenario set for this run. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set being executed (must exist at run create). `status` string (enum) optional Example: `SIMULATION_RUN_STATUS_UNSPECIFIED` Lifecycle status of a simulation run. - SIMULATION_RUN_STATUS_PENDING: Accepted and queued, not yet executing. - SIMULATION_RUN_STATUS_RUNNING: Journeys are executing. - SIMULATION_RUN_STATUS_SUCCEEDED: All journeys finished successfully. - SIMULATION_RUN_STATUS_FAILED: The run failed, for example because of a timeout or workflow error. - SIMULATION_RUN_STATUS_CANCELLED: The run was cancelled. - SIMULATION_RUN_STATUS_EVALUATING: Journeys finished and an attached evaluation is running. Only reachable when the create request included evaluation_config. When the evaluation reaches a terminal status, its outcome is reflected in the simulation run status. - SIMULATION_RUN_STATUS_PARTIALLY_SUCCESSFUL: The simulation or its attached evaluation completed with a mixture of successful and failed results. `total_journeys` integer (int64) optional Example: `123` Total number of journeys (sum of exploration budgets). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `user_simulator_config` object optional Optional user simulator model settings such as temperature and max_tokens. `user_simulator_model_name` string optional Example: `example name` Display name of the user simulator model (from the model catalog). `user_simulator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model used by the user simulator. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the workflow executing this 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "simulation_run": { "agent_config": { "agent_deployment_uuid": "123e4567-e89b-12d3-a456-426614174000", "agent_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name" }, "created_at": "2023-01-01T00:00:00Z", "created_by_user_email": "example@example.com", "created_by_user_id": "12345", "deleted_at": "2023-01-01T00:00:00Z", "evaluation_run_uuid": "123e4567-e89b-12d3-a456-426614174000", "exploration_budget": 123, "failure_reason": "example string", "journeys_finished": 123, "judge_model_name": "example name", "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "max_turns": 123, "name": "example name", "result_summary": { "total_duration_sec": "12345" }, "run_uuid": "123e4567-e89b-12d3-a456-426614174000", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "status": "SIMULATION_RUN_STATUS_UNSPECIFIED", "total_journeys": 123, "updated_at": "2023-01-01T00:00:00Z", "user_simulator_model_name": "example name", "user_simulator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete Simulation Run `/v2/gen-ai/simulation_runs/{run_uuid}` To delete a simulation run, send a DELETE request to `/v2/gen-ai/simulation_runs/{run_uuid}`. The run must be in a terminal status (`SIMULATION_RUN_STATUS_SUCCEEDED`, `SIMULATION_RUN_STATUS_PARTIALLY_SUCCESSFUL`, `SIMULATION_RUN_STATUS_FAILED`, or `SIMULATION_RUN_STATUS_CANCELLED`). For runs still in progress, cancel the run first, then retry the delete. #### Path Parameters `run_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the simulation run to delete. The run must be in a terminal status. For runs still in progress, cancel the run first, then retry the delete. ##### Request: `/v2/gen-ai/simulation_runs/{run_uuid}` ### cURL ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/simulation_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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the deleted 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "run_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PATCH Cancel Simulation Run `/v2/gen-ai/simulation_runs/{run_uuid}/cancel` To cancel an in-progress simulation run, send a PATCH request to `/v2/gen-ai/simulation_runs/{run_uuid}/cancel`. #### Path Parameters `run_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the simulation run to cancel. Returned by `CreateSimulationRun` and listed via `ListSimulationRuns`. The run must be in a non-terminal status; already-terminal runs return an error. #### Request Body: `application/json` `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the run to cancel. ##### Request: `/v2/gen-ai/simulation_runs/{run_uuid}/cancel` ### Payload Content type `application/json` ```json { "run_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` ### cURL ```bash curl -X PATCH \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/simulation_runs/12345678-1234-1234-1234-123456789012/cancel" \ -d '{ "run_uuid": "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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `simulation_run` object optional One execution of a scenario set against a candidate agent. **Show child properties** `agent_config` object optional Configuration of the candidate agent under test for a simulation run. **Show child properties** `agent_deployment_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional agent deployment to run. Defaults to the agent's current deployment when unset. `agent_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the agent to exercise as the candidate. `name` string optional Example: `example name` Display name of the candidate agent. Persisted with the run. `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `created_by_user_email` string optional Example: `example@example.com` Email of the user who triggered this run. `created_by_user_id` string (uint64) optional Example: `12345` User id of the actor who triggered this run. `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time deleted at. Unset unless the run has been deleted. `evaluation_run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the evaluation run reserved for this simulation, when the create request included evaluation_config. Empty when no evaluation is attached. `exploration_budget` integer (int64) optional Example: `123` Optional run-level journeys-per-scenario override. When set, overrides each scenario's exploration_budget. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `journeys_finished` integer (int64) optional Example: `123` Number of journeys that have finished (successfully or not). `judge_model_name` string optional Example: `example name` Display name of the judge model (from the model catalog). `judge_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model used by the judge. `max_turns` integer (int64) optional Example: `123` Optional run-level turn budget. When set, overrides each scenario's max_turns. `name` string optional Example: `example name` Optional run name. `result_summary` object optional Aggregated final result of a simulation run: verdict counts plus token and duration totals. **Show child properties** `token_usage` object optional Per-actor token accounting for a run or journey. **Show child properties** `candidate_agent_tokens` string (uint64) optional Example: `12345` Tokens consumed by the candidate agent. `generator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the scenario generator. `judge_tokens` string (uint64) optional Example: `12345` Tokens consumed by the judge. `simulator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the user simulator. `total_tokens` string (uint64) optional Example: `12345` Total tokens across all actors. `total_duration_sec` string (uint64) optional Example: `12345` Total wall-clock duration across the run, in seconds. `verdict_counts` object optional Breakdown of journey outcomes by judge verdict. Reused wherever a success / failure / inconclusive tally is reported (run row, result summary, per-scenario rollup). **Show child properties** `failure_count` integer (int64) optional Example: `123` Number of journeys with a FAILURE verdict. `inconclusive_count` integer (int64) optional Example: `123` Number of journeys with an INCONCLUSIVE verdict. `success_count` integer (int64) optional Example: `123` Number of journeys with a SUCCESS verdict. `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the run. `scenario_count` integer (int64) optional Example: `123` Number of scenarios in the scenario set for this run. `scenario_set_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario set being executed (must exist at run create). `status` string (enum) optional Example: `SIMULATION_RUN_STATUS_UNSPECIFIED` Lifecycle status of a simulation run. - SIMULATION_RUN_STATUS_PENDING: Accepted and queued, not yet executing. - SIMULATION_RUN_STATUS_RUNNING: Journeys are executing. - SIMULATION_RUN_STATUS_SUCCEEDED: All journeys finished successfully. - SIMULATION_RUN_STATUS_FAILED: The run failed, for example because of a timeout or workflow error. - SIMULATION_RUN_STATUS_CANCELLED: The run was cancelled. - SIMULATION_RUN_STATUS_EVALUATING: Journeys finished and an attached evaluation is running. Only reachable when the create request included evaluation_config. When the evaluation reaches a terminal status, its outcome is reflected in the simulation run status. - SIMULATION_RUN_STATUS_PARTIALLY_SUCCESSFUL: The simulation or its attached evaluation completed with a mixture of successful and failed results. `total_journeys` integer (int64) optional Example: `123` Total number of journeys (sum of exploration budgets). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `user_simulator_config` object optional Optional user simulator model settings such as temperature and max_tokens. `user_simulator_model_name` string optional Example: `example name` Display name of the user simulator model (from the model catalog). `user_simulator_model_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Model used by the user simulator. `workflow_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the workflow executing this 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "simulation_run": { "agent_config": { "agent_deployment_uuid": "123e4567-e89b-12d3-a456-426614174000", "agent_uuid": "123e4567-e89b-12d3-a456-426614174000", "name": "example name" }, "created_at": "2023-01-01T00:00:00Z", "created_by_user_email": "example@example.com", "created_by_user_id": "12345", "deleted_at": "2023-01-01T00:00:00Z", "evaluation_run_uuid": "123e4567-e89b-12d3-a456-426614174000", "exploration_budget": 123, "failure_reason": "example string", "journeys_finished": 123, "judge_model_name": "example name", "judge_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "max_turns": 123, "name": "example name", "result_summary": { "total_duration_sec": "12345" }, "run_uuid": "123e4567-e89b-12d3-a456-426614174000", "scenario_count": 123, "scenario_set_uuid": "123e4567-e89b-12d3-a456-426614174000", "status": "SIMULATION_RUN_STATUS_UNSPECIFIED", "total_journeys": 123, "updated_at": "2023-01-01T00:00:00Z", "user_simulator_model_name": "example name", "user_simulator_model_uuid": "123e4567-e89b-12d3-a456-426614174000", "workflow_uuid": "123e4567-e89b-12d3-a456-426614174000" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Simulation Journeys `/v2/gen-ai/simulation_runs/{run_uuid}/journeys` To list the journeys within a simulation run, send a GET request to `/v2/gen-ai/simulation_runs/{run_uuid}/journeys`. #### Path Parameters `run_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the run whose journeys to list. #### Query Parameters `scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Optional filter by scenario. `page` integer optional Example: `1` Page number. `per_page` integer optional Example: `1` Items per page. `statuses` array of string, one of: SIMULATION_JOURNEY_STATUS_UNSPECIFIED, SIMULATION_JOURNEY_STATUS_RUNNING, SIMULATION_JOURNEY_STATUS_FINISHED, SIMULATION_JOURNEY_STATUS_FAILED, SIMULATION_JOURNEY_STATUS_PREPARING optional Example: `["SIMULATION_JOURNEY_STATUS_FINISHED"]` Filter by one or more statuses. Empty means no status filter. - SIMULATION_JOURNEY_STATUS_RUNNING: The journey is executing and a trajectory is available to retrieve. - SIMULATION_JOURNEY_STATUS_FINISHED: The journey reached a stop condition and produced a verdict. - SIMULATION_JOURNEY_STATUS_FAILED: The journey failed because of a cancel, timeout, or error. - SIMULATION_JOURNEY_STATUS_PREPARING: The journey is allocated but its trajectory is not available yet. `verdicts` array of string, one of: SIMULATION_JOURNEY_VERDICT_UNSPECIFIED, SIMULATION_JOURNEY_VERDICT_SUCCESS, SIMULATION_JOURNEY_VERDICT_FAILURE, SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE optional Example: `["SIMULATION_JOURNEY_VERDICT_SUCCESS"]` Filter by one or more verdicts. Empty means no verdict filter. - SIMULATION_JOURNEY_VERDICT_SUCCESS: The candidate agent satisfied the scenario's stopping criteria. - SIMULATION_JOURNEY_VERDICT_FAILURE: The candidate agent did not satisfy the stopping criteria. - SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE: No conclusive verdict (e.g. max_turns reached without the judge finishing). `search` string optional Example: `example string` Free-text search across scenario_uuid and session_id (case-insensitive substring match). Empty means no search. `sort_by` string, one of: SIMULATION_JOURNEY_SORT_FIELD_UNSPECIFIED, SIMULATION_JOURNEY_SORT_FIELD_SCENARIO, SIMULATION_JOURNEY_SORT_FIELD_CREATED_AT, SIMULATION_JOURNEY_SORT_FIELD_STATUS, SIMULATION_JOURNEY_SORT_FIELD_VERDICT optional Example: `SIMULATION_JOURNEY_SORT_FIELD_UNSPECIFIED` Field to sort by. Defaults to scenario ordering when unspecified. - SIMULATION_JOURNEY_SORT_FIELD_SCENARIO: Sort by scenario_uuid then journey_index. Default. - SIMULATION_JOURNEY_SORT_FIELD_CREATED_AT: Sort by creation date. - SIMULATION_JOURNEY_SORT_FIELD_STATUS: Sort by journey status using lifecycle order. - SIMULATION_JOURNEY_SORT_FIELD_VERDICT: Sort by verdict (nulls last). Default: `SIMULATION_JOURNEY_SORT_FIELD_UNSPECIFIED` `sort_direction` string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Example: `SORT_DIRECTION_UNSPECIFIED` Sort direction. Defaults to ascending when unspecified. Default: `SORT_DIRECTION_UNSPECIFIED` ##### Request: `/v2/gen-ai/simulation_runs/{run_uuid}/journeys` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/simulation_runs/12345678-1234-1234-1234-123456789012/journeys" ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `available_sort_by` array of string, one of: SIMULATION_JOURNEY_SORT_FIELD_UNSPECIFIED, SIMULATION_JOURNEY_SORT_FIELD_SCENARIO, SIMULATION_JOURNEY_SORT_FIELD_CREATED_AT, SIMULATION_JOURNEY_SORT_FIELD_STATUS, SIMULATION_JOURNEY_SORT_FIELD_VERDICT optional Sort-by values available for this list request. `available_sort_directions` array of string, one of: SORT_DIRECTION_UNSPECIFIED, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC optional Sort-direction values available for this list request. `available_statuses` array of string, one of: SIMULATION_JOURNEY_STATUS_UNSPECIFIED, SIMULATION_JOURNEY_STATUS_RUNNING, SIMULATION_JOURNEY_STATUS_FINISHED, SIMULATION_JOURNEY_STATUS_FAILED, SIMULATION_JOURNEY_STATUS_PREPARING optional Statuses available for filtering this list request. `available_verdicts` array of string, one of: SIMULATION_JOURNEY_VERDICT_UNSPECIFIED, SIMULATION_JOURNEY_VERDICT_SUCCESS, SIMULATION_JOURNEY_VERDICT_FAILURE, SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE optional Verdicts available for filtering this list request. `journeys` array of object optional The journeys for the current page. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `duration_sec` string (uint64) optional Example: `12345` Wall-clock time taken for the journey to complete, in seconds. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `journey_index` integer (int64) optional Example: `123` Zero-based index of this journey within its scenario's exploration budget. `journey_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the journey. `judge_reasoning` string optional Example: `example string` Optional judge reasoning for the verdict. `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the run this journey belongs to. `scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario this journey executed. `session_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Session identifier for this journey. `status` string, one of: SIMULATION_JOURNEY_STATUS_UNSPECIFIED, SIMULATION_JOURNEY_STATUS_RUNNING, SIMULATION_JOURNEY_STATUS_FINISHED, SIMULATION_JOURNEY_STATUS_FAILED, SIMULATION_JOURNEY_STATUS_PREPARING optional Example: `SIMULATION_JOURNEY_STATUS_UNSPECIFIED` Lifecycle status of a single journey. - SIMULATION_JOURNEY_STATUS_RUNNING: The journey is executing and a trajectory is available to retrieve. - SIMULATION_JOURNEY_STATUS_FINISHED: The journey reached a stop condition and produced a verdict. - SIMULATION_JOURNEY_STATUS_FAILED: The journey failed because of a cancel, timeout, or error. - SIMULATION_JOURNEY_STATUS_PREPARING: The journey is allocated but its trajectory is not available yet. `token_usage` object optional Per-actor token accounting for a run or journey. **Show child properties** `candidate_agent_tokens` string (uint64) optional Example: `12345` Tokens consumed by the candidate agent. `generator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the scenario generator. `judge_tokens` string (uint64) optional Example: `12345` Tokens consumed by the judge. `simulator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the user simulator. `total_tokens` string (uint64) optional Example: `12345` Total tokens across all actors. `trajectory_bucket_name` string optional Example: `example name` Object storage bucket holding the trajectory JSON. Set when the journey finishes. `trajectory_bucket_region` string optional Example: `example string` Object storage bucket region for the trajectory JSON. Set when the journey finishes. `trajectory_spaces_key` string optional Example: `example string` Object storage key for the trajectory JSON. Set when the journey finishes. `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `verdict` string, one of: SIMULATION_JOURNEY_VERDICT_UNSPECIFIED, SIMULATION_JOURNEY_VERDICT_SUCCESS, SIMULATION_JOURNEY_VERDICT_FAILURE, SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE optional Example: `SIMULATION_JOURNEY_VERDICT_UNSPECIFIED` The judge's verdict for a journey. - SIMULATION_JOURNEY_VERDICT_SUCCESS: The candidate agent satisfied the scenario's stopping criteria. - SIMULATION_JOURNEY_VERDICT_FAILURE: The candidate agent did not satisfy the stopping criteria. - SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE: No conclusive verdict (e.g. max_turns reached without the judge finishing). `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "available_sort_by": [ "SIMULATION_JOURNEY_SORT_FIELD_UNSPECIFIED" ], "available_sort_directions": [ "SORT_DIRECTION_UNSPECIFIED" ], "available_statuses": [ "SIMULATION_JOURNEY_STATUS_UNSPECIFIED" ], "available_verdicts": [ "SIMULATION_JOURNEY_VERDICT_UNSPECIFIED" ], "journeys": [ { "created_at": "2023-01-01T00:00:00Z", "duration_sec": "12345", "failure_reason": "example string", "journey_index": 123, "journey_uuid": "123e4567-e89b-12d3-a456-426614174000", "judge_reasoning": "example string", "run_uuid": "123e4567-e89b-12d3-a456-426614174000", "scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "session_id": "123e4567-e89b-12d3-a456-426614174000", "status": "SIMULATION_JOURNEY_STATUS_UNSPECIFIED", "trajectory_bucket_name": "example name", "trajectory_bucket_region": "example string", "trajectory_spaces_key": "example string", "updated_at": "2023-01-01T00:00:00Z", "verdict": "SIMULATION_JOURNEY_VERDICT_UNSPECIFIED" } ], "links": { "pages": { "first": "example string", "last": "example string", "next": "example string", "previous": "example string" } }, "meta": { "page": 123, "pages": 123, "total": 123 } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Simulation Journey `/v2/gen-ai/simulation_runs/{run_uuid}/journeys/{journey_uuid}` To retrieve a single journey, send a GET request to `/v2/gen-ai/simulation_runs/{run_uuid}/journeys/{journey_uuid}`. #### Path Parameters `run_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the run the journey belongs to. `journey_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the journey. ##### Request: `/v2/gen-ai/simulation_runs/{run_uuid}/journeys/{journey_uuid}` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/simulation_runs/12345678-1234-1234-1234-123456789012/journeys/abcdef01-2345-6789-abcd-ef0123456789" ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `journey` object optional One independent execution within a simulation run, including its trajectory and verdict. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time created at. `duration_sec` string (uint64) optional Example: `12345` Wall-clock time taken for the journey to complete, in seconds. `failure_reason` string optional Example: `example string` Human-readable explanation of a terminal FAILED status. Empty otherwise. `journey_index` integer (int64) optional Example: `123` Zero-based index of this journey within its scenario's exploration budget. `journey_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the journey. `judge_reasoning` string optional Example: `example string` Optional judge reasoning for the verdict. `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the run this journey belongs to. `scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` UUID of the scenario this journey executed. `session_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Session identifier for this journey. `status` string, one of: SIMULATION_JOURNEY_STATUS_UNSPECIFIED, SIMULATION_JOURNEY_STATUS_RUNNING, SIMULATION_JOURNEY_STATUS_FINISHED, SIMULATION_JOURNEY_STATUS_FAILED, SIMULATION_JOURNEY_STATUS_PREPARING optional Example: `SIMULATION_JOURNEY_STATUS_UNSPECIFIED` Lifecycle status of a single journey. - SIMULATION_JOURNEY_STATUS_RUNNING: The journey is executing and a trajectory is available to retrieve. - SIMULATION_JOURNEY_STATUS_FINISHED: The journey reached a stop condition and produced a verdict. - SIMULATION_JOURNEY_STATUS_FAILED: The journey failed because of a cancel, timeout, or error. - SIMULATION_JOURNEY_STATUS_PREPARING: The journey is allocated but its trajectory is not available yet. `token_usage` object optional Per-actor token accounting for a run or journey. **Show child properties** `candidate_agent_tokens` string (uint64) optional Example: `12345` Tokens consumed by the candidate agent. `generator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the scenario generator. `judge_tokens` string (uint64) optional Example: `12345` Tokens consumed by the judge. `simulator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the user simulator. `total_tokens` string (uint64) optional Example: `12345` Total tokens across all actors. `trajectory_bucket_name` string optional Example: `example name` Object storage bucket holding the trajectory JSON. Set when the journey finishes. `trajectory_bucket_region` string optional Example: `example string` Object storage bucket region for the trajectory JSON. Set when the journey finishes. `trajectory_spaces_key` string optional Example: `example string` Object storage key for the trajectory JSON. Set when the journey finishes. `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Time last updated at. `verdict` string, one of: SIMULATION_JOURNEY_VERDICT_UNSPECIFIED, SIMULATION_JOURNEY_VERDICT_SUCCESS, SIMULATION_JOURNEY_VERDICT_FAILURE, SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE optional Example: `SIMULATION_JOURNEY_VERDICT_UNSPECIFIED` The judge's verdict for a journey. - SIMULATION_JOURNEY_VERDICT_SUCCESS: The candidate agent satisfied the scenario's stopping criteria. - SIMULATION_JOURNEY_VERDICT_FAILURE: The candidate agent did not satisfy the stopping criteria. - SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE: No conclusive verdict (e.g. max_turns reached without the judge finishing). **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "journey": { "created_at": "2023-01-01T00:00:00Z", "duration_sec": "12345", "failure_reason": "example string", "journey_index": 123, "journey_uuid": "123e4567-e89b-12d3-a456-426614174000", "judge_reasoning": "example string", "run_uuid": "123e4567-e89b-12d3-a456-426614174000", "scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "session_id": "123e4567-e89b-12d3-a456-426614174000", "status": "SIMULATION_JOURNEY_STATUS_UNSPECIFIED", "token_usage": { "candidate_agent_tokens": "12345", "generator_tokens": "12345", "judge_tokens": "12345", "simulator_tokens": "12345", "total_tokens": "12345" }, "trajectory_bucket_name": "example name", "trajectory_bucket_region": "example string", "trajectory_spaces_key": "example string", "updated_at": "2023-01-01T00:00:00Z", "verdict": "SIMULATION_JOURNEY_VERDICT_UNSPECIFIED" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Journey Trajectory `/v2/gen-ai/simulation_runs/{run_uuid}/journeys/{journey_uuid}/trajectory` To retrieve a journey's live trajectory, send a GET request to `/v2/gen-ai/simulation_runs/{run_uuid}/journeys/{journey_uuid}/trajectory`. Poll while the journey is running to watch turn-by-turn progress. #### Path Parameters `run_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the run the journey belongs to. `journey_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the journey. ##### Request: `/v2/gen-ai/simulation_runs/{run_uuid}/journeys/{journey_uuid}/trajectory` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/simulation_runs/12345678-1234-1234-1234-123456789012/journeys/abcdef01-2345-6789-abcd-ef0123456789/trajectory" ``` #### 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](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `trajectory` object optional Turn-by-turn trajectory for one journey. Poll this resource while the journey is running to watch live progress. **Show child properties** `agent_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Identifier of the candidate agent under test for this journey. `completed_at` string optional Example: `example string` `duration_sec` string (uint64) optional Example: `12345` `evaluation_metrics` array of object optional Per-metric scores and judge reasoning for this trajectory. Empty when the simulation run has no associated evaluation. **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_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Metric UUID (built-in or custom); stable key for results UI and aggregation. `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. `status` string, one of: EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED, EVALUATION_METRIC_RESULT_STATUS_COMPLETED, EVALUATION_METRIC_RESULT_STATUS_FAILED, EVALUATION_METRIC_RESULT_STATUS_SKIPPED optional Example: `EVALUATION_METRIC_RESULT_STATUS_UNSPECIFIED` Outcome of scoring a single metric for one prompt or span. `string_value` string optional Example: `example string` The value of the metric as a string. `failure_reason` string optional Example: `example string` `journey_index` integer (int64) optional Example: `123` `journey_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `judge` object optional Judge output embedded in the trajectory JSON. **Show child properties** `criteria_pass_fail` array of object optional **Show child properties** `criterion` string optional Example: `example string` `passed` boolean optional Example: `true` `reasoning` string optional Example: `example string` `reasoning` string optional Example: `example string` `verdict` string, one of: SIMULATION_JOURNEY_VERDICT_UNSPECIFIED, SIMULATION_JOURNEY_VERDICT_SUCCESS, SIMULATION_JOURNEY_VERDICT_FAILURE, SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE optional Example: `SIMULATION_JOURNEY_VERDICT_UNSPECIFIED` The judge's verdict for a journey. - SIMULATION_JOURNEY_VERDICT_SUCCESS: The candidate agent satisfied the scenario's stopping criteria. - SIMULATION_JOURNEY_VERDICT_FAILURE: The candidate agent did not satisfy the stopping criteria. - SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE: No conclusive verdict (e.g. max_turns reached without the judge finishing). `max_turns` integer (int64) optional Example: `123` Turn budget configured for this journey (per-scenario max_turns, after any run-level override). Compare with turn_count to see how many of the budgeted turns actually ran. `messages` array of object optional **Show child properties** `completed_at` string optional Example: `example string` ISO-8601 timestamp when the message completed. `content` string optional Example: `example string` Message body text. `role` string optional Example: `example string` Message role: "user" or "assistant". `started_at` string optional Example: `example string` ISO-8601 timestamp when the message started. `tokens` object optional Token usage for a single assistant message in the trajectory JSON. **Show child properties** `input` integer (int64) optional Example: `123` `output` integer (int64) optional Example: `123` `tool_calls` array of object optional Tool calls on assistant turns. **Show child properties** `description` string optional Example: `example string` `input_parameters` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `ok` boolean optional Example: `true` `output` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `tool_call_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `turn_index` integer (int64) optional Example: `123` Zero-based turn index shared by the user and assistant messages in one exchange. `run_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `scenario_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `session_id` string optional Example: `123e4567-e89b-12d3-a456-426614174000` `started_at` string optional Example: `example string` `status` string, one of: SIMULATION_TRAJECTORY_STATUS_UNSPECIFIED, SIMULATION_TRAJECTORY_STATUS_RUNNING, SIMULATION_TRAJECTORY_STATUS_COMPLETED, SIMULATION_TRAJECTORY_STATUS_FAILED, SIMULATION_TRAJECTORY_STATUS_CANCELLED optional Example: `SIMULATION_TRAJECTORY_STATUS_UNSPECIFIED` Lifecycle status of the trajectory. Distinct from journey status: the trajectory is updated on every turn while the journey is executing. - SIMULATION_TRAJECTORY_STATUS_RUNNING: The journey loop is in progress; messages may grow on each poll. - SIMULATION_TRAJECTORY_STATUS_COMPLETED: The journey reached a stop condition and the trajectory is complete. - SIMULATION_TRAJECTORY_STATUS_FAILED: The journey failed before or during execution. - SIMULATION_TRAJECTORY_STATUS_CANCELLED: The journey was cancelled. `token_usage` object optional Per-actor token accounting for a run or journey. **Show child properties** `candidate_agent_tokens` string (uint64) optional Example: `12345` Tokens consumed by the candidate agent. `generator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the scenario generator. `judge_tokens` string (uint64) optional Example: `12345` Tokens consumed by the judge. `simulator_tokens` string (uint64) optional Example: `12345` Tokens consumed by the user simulator. `total_tokens` string (uint64) optional Example: `12345` Total tokens across all actors. `turn_count` integer (int64) optional Example: `123` `verdict` string, one of: SIMULATION_JOURNEY_VERDICT_UNSPECIFIED, SIMULATION_JOURNEY_VERDICT_SUCCESS, SIMULATION_JOURNEY_VERDICT_FAILURE, SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE optional Example: `SIMULATION_JOURNEY_VERDICT_UNSPECIFIED` The judge's verdict for a journey. - SIMULATION_JOURNEY_VERDICT_SUCCESS: The candidate agent satisfied the scenario's stopping criteria. - SIMULATION_JOURNEY_VERDICT_FAILURE: The candidate agent did not satisfy the stopping criteria. - SIMULATION_JOURNEY_VERDICT_INCONCLUSIVE: No conclusive verdict (e.g. max_turns reached without the judge finishing). **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "trajectory": { "agent_id": "123e4567-e89b-12d3-a456-426614174000", "completed_at": "example string", "duration_sec": "12345", "evaluation_metrics": [], "failure_reason": "example string", "journey_index": 123, "journey_uuid": "123e4567-e89b-12d3-a456-426614174000", "judge": { "criteria_pass_fail": [], "reasoning": "example string", "verdict": "SIMULATION_JOURNEY_VERDICT_UNSPECIFIED" }, "max_turns": 123, "messages": [], "run_uuid": "123e4567-e89b-12d3-a456-426614174000", "scenario_uuid": "123e4567-e89b-12d3-a456-426614174000", "session_id": "123e4567-e89b-12d3-a456-426614174000", "started_at": "example string", "status": "SIMULATION_TRAJECTORY_STATUS_UNSPECIFIED", "token_usage": { "candidate_agent_tokens": "12345", "generator_tokens": "12345", "judge_tokens": "12345", "simulator_tokens": "12345", "total_tokens": "12345" }, "turn_count": 123, "verdict": "SIMULATION_JOURNEY_VERDICT_UNSPECIFIED" } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve Journey Trajectory Download URL `/v2/gen-ai/simulation_runs/{run_uuid}/journeys/{journey_uuid}/trajectory_url` To retrieve a presigned download URL for a journey's trajectory, send a GET request to `/v2/gen-ai/simulation_runs/{run_uuid}/journeys/{journey_uuid}/trajectory_url`. #### Path Parameters `run_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the run the journey belongs to. `journey_uuid` string required Example: `"123e4567-e89b-12d3-a456-426614174000"` UUID of the journey. ##### Request: `/v2/gen-ai/simulation_runs/{run_uuid}/journeys/{journey_uuid}/trajectory_url` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/simulation_runs/12345678-1234-1234-1234-123456789012/journeys/abcdef01-2345-6789-abcd-ef0123456789/trajectory_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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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 trajectory JSON 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 The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "download_url": "example string", "expires_at": "2023-01-01T00:00:00Z" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Workspaces `/v2/gen-ai/workspaces` To list all workspaces, send a GET request to `/v2/gen-ai/workspaces`. ##### Request: `/v2/gen-ai/workspaces` ### cURL ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/workspaces" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` Name `output_schema` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `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_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` EvaluationDatasetParadigm is the row/content shape of a dataset, orthogonal to the surface in EvaluationDatasetType (e.g. a model dataset can be single- or multi-turn). `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** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "workspaces": [ { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## POST Create a Workspace `/v2/gen-ai/workspaces` 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` ```json { "agent_uuids": [ "example string" ], "description": "example string", "name": "example name" } ``` ### cURL ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/workspaces" \ -d '{ "name": "api-create", "description": "This is a test workspace created via the API", "agent_uuids": [ "9758a232-b351-11ef-bf8f-4e013e2ddde4" ] }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` Name `output_schema` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `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_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` EvaluationDatasetParadigm is the row/content shape of a dataset, orthogonal to the surface in EvaluationDatasetType (e.g. a model dataset can be single- or multi-turn). `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** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET Retrieve an Existing Workspace `/v2/gen-ai/workspaces/{workspace_uuid}` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/workspaces/c441bf77-81d6-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` Name `output_schema` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `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_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` EvaluationDatasetParadigm is the row/content shape of a dataset, orthogonal to the surface in EvaluationDatasetType (e.g. a model dataset can be single- or multi-turn). `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** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Update a Workspace `/v2/gen-ai/workspaces/{workspace_uuid}` 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` ```json { "description": "example string", "name": "example name", "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/workspaces/1b418231-b7d6-11ef-bf8f-4e013e2ddde4" \ -d '{ "workspace_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "name": "rename-agent-api", "description": "workspace description" }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` Name `output_schema` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `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_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` EvaluationDatasetParadigm is the row/content shape of a dataset, orthogonal to the surface in EvaluationDatasetType (e.g. a model dataset can be single- or multi-turn). `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** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## DELETE Delete a Workspace `/v2/gen-ai/workspaces/{workspace_uuid}` 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 ```bash curl -X DELETE \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/workspaces/5581a586-a745-11ef-bf8f-4e013e2ddde4" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `workspace_uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Workspace **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List agents by Workspace `/v2/gen-ai/workspaces/{workspace_uuid}/agents` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/workspaces/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/agents" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `created_by_user_id` string (uint64) optional Example: `12345` `dataset` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` `star_metric` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id `links` object optional Links to other pages **Show child properties** `pages` object optional Information about how to reach other pages **Show child properties** `first` string optional Example: `example string` First page `last` string optional Example: `example string` Last page `next` string optional Example: `example string` Next page `previous` string optional Example: `example string` Previous page `meta` object optional Meta information about the data set **Show child properties** `page` integer (int64) optional Example: `123` The current page `pages` integer (int64) optional Example: `123` Total number of pages `total` integer (int64) optional Example: `123` Total amount of items over all pages **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "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\"", "web_fetch_enabled": true, "web_search_enabled": true } ], "links": { "pages": { "first": "example string", "last": "example string", "next": "example string", "previous": "example string" } }, "meta": { "page": 123, "pages": 123, "total": 123 } } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## PUT Move Agents to a Workspace `/v2/gen-ai/workspaces/{workspace_uuid}/agents` 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` ```json { "agent_uuids": [ "example string" ], "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000" } ``` ### cURL ```bash curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/workspaces/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/agents" \ -d '{ "workspace_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "agent_uuids": ["95ea6652-75ed-11ef-bf8f-4e013e2ddde4", "37455431-84bd-4fa2-94cf-e8486f8f8c5e"] }' ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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](https://github.com/digitalocean/openapi) for details.* `name` string optional Example: `example name` Name `output_schema` object optional *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/index.html.md#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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) for details.* `modalities` object optional Input/output modalities *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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](https://github.com/digitalocean/openapi) 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"` `web_fetch_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_fetch tool. `web_search_enabled` boolean optional Example: `true` Whether this agent can use the built-in web_search tool. `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: `example@example.com` 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: `example@example.com` `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_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` EvaluationDatasetParadigm is the row/content shape of a dataset, orthogonal to the surface in EvaluationDatasetType (e.g. a model dataset can be single- or multi-turn). `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** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. *Additional nested properties not shown. Refer to the [full API spec](https://github.com/digitalocean/openapi) for details.* `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` `name` string optional Example: `example name` Name of the workspace `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` Update date `uuid` string optional Example: `123e4567-e89b-12d3-a456-426614174000` Unique id **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "workspace": { "agents": [], "created_at": "2023-01-01T00:00:00Z", "created_by": "12345", "created_by_email": "example@example.com", "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** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * ## GET List Evaluation Test Cases by Workspace `/v2/gen-ai/workspaces/{workspace_uuid}/evaluation_test_cases` 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 ```bash curl -X GET \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ "https://api.digitalocean.com/v2/gen-ai/workspaces/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/evaluation_test_cases" ``` #### Responses **200** A successful response. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#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: `example@example.com` `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_paradigm` string, one of: EVALUATION_DATASET_PARADIGM_SINGLE_TURN, EVALUATION_DATASET_PARADIGM_MULTI_TURN, EVALUATION_DATASET_PARADIGM_CODING, EVALUATION_DATASET_PARADIGM_N_PLUS_1 optional Example: `EVALUATION_DATASET_PARADIGM_SINGLE_TURN` EvaluationDatasetParadigm is the row/content shape of a dataset, orthogonal to the surface in EvaluationDatasetType (e.g. a model dataset can be single- or multi-turn). `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** `associated_presets` array of object optional Saved model evaluation presets that reference this metric. Populated for custom metrics when listing metrics so the dashboard can warn that deleting the metric will also delete these presets. Empty for built-in metrics. **Show child properties** `eval_preset_uuid` string optional Example: `"12345678-1234-1234-1234-123456789012"` Unique identifier of the saved model evaluation preset that references the metric. `name` string optional Example: `"My evaluation preset"` Display name of the saved model evaluation preset. `category` string (enum) optional Example: `METRIC_CATEGORY_UNSPECIFIED` `custom_eval_config` object optional Configuration for a custom model-evaluation metric scored by an LLM judge. Prompt and model response are always included in the judge context. **Show child properties** `created_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `deleted_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` When set, the custom metric is soft-deleted and must not appear in pickers. `requires_ground_truth` boolean optional Example: `true` When true, each row must provide ground truth and it is included in the judge context. When false, ground truth is not required and is not sent to the judge. `scoring_prompt` string optional Example: `example string` Instructions for the judge model (multi-line). `updated_at` string (date-time) optional Example: `2023-01-01T00:00:00Z` `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. `source` string, one of: EVALUATION_METRIC_SOURCE_UNSPECIFIED, EVALUATION_METRIC_SOURCE_BUILTIN, EVALUATION_METRIC_SOURCE_CUSTOM optional Example: `EVALUATION_METRIC_SOURCE_UNSPECIFIED` Distinguishes platform catalog metrics from user-defined LLM-as-judge metrics. `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: `example@example.com` `updated_by_user_id` string (uint64) optional Example: `12345` `version` integer (int64) optional Example: `123` **401** Authentication failed due to invalid credentials. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **404** The resource was not found. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **429** The API rate limit has been exceeded. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **500** There was a server error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. **default** There was an unexpected error. Response Headers `ratelimit-limit` integer The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. `ratelimit-remaining` integer The number of requests in your hourly quota that remain before you hit your request limit. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. `ratelimit-reset` integer The time when the oldest request will expire. The value is given in Unix epoch time. See [https://docs.digitalocean.com/reference/api/reference/#rate-limit](https://docs.digitalocean.com/reference/api/reference/index.html.md#rate-limit) for information about how requests expire. Response Schema: `application/json` `id` string required Example: `not_found` A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." `message` string required Example: `The resource you were accessing could not be found.` A message providing additional information about the error, including details to help resolve it when possible. `request_id` string optional Example: `4d9d8375-3c56-4925-a3e7-eb137fed17e9` 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** ```json { "evaluation_test_cases": [ { "archived_at": "2023-01-01T00:00:00Z", "created_at": "2023-01-01T00:00:00Z", "created_by_user_email": "example@example.com", "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": "example@example.com", "updated_by_user_id": "12345", "version": 123 } ] } ``` **401** ```json { "id": "unauthorized", "message": "Unable to authenticate you." } ``` **404** ```json { "id": "not_found", "message": "The resource you requested could not be found." } ``` **429** ```json { "id": "too_many_requests", "message": "API rate limit exceeded." } ``` **500** ```json { "id": "server_error", "message": "Unexpected server-side error" } ``` **default** ```json { "id": "example_error", "message": "some error message" } ``` * * * Learn more: [Inference Pricing](https://docs.digitalocean.com/products/inference/details/pricing/index.html.md), [Supported Models on DigitalOcean Inference](https://docs.digitalocean.com/products/inference/details/models/index.html.md), [Use Serverless Inference](https://docs.digitalocean.com/products/inference/how-to/use-serverless-inference/index.html.md)